blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/structures/systems/merkle.py

@@ -0,0 +1,273 @@
+"""Domain-separated Merkle trees with explicit leaf-count commitments.
+
+Odd nodes are promoted unchanged. Roots bind the leaf count to avoid
+ambiguity between differently shaped trees. This is not Bitcoin's format.
+"""
+
+from collections.abc import Iterable
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import (
+    MERKLE_LEAF_PREFIX,
+    MERKLE_NODE_PREFIX,
+    MERKLE_ROOT_PREFIX,
+    UINT64_LIMIT,
+)
+from blockchainkit.crypto.systems.hashing import hash256, sha256
+from blockchainkit.structures.core.base import MerkleProof, MerkleTrace, ProofStep
+
+
+def _root(count: int, digest: bytes) -> bytes:
+    return sha256(MERKLE_ROOT_PREFIX + count.to_bytes(8, "big") + digest)
+
+
+class MerkleTree:
+    """Build a tree from an iterable of byte strings.
+
+    Parameters
+    ----------
+    leaves : iterable of bytes
+        Ordered payloads, hashed as SHA256(0x00 || payload).
+
+    Examples
+    --------
+    >>> from blockchainkit.structures import MerkleTree, verify_proof
+    >>> tree = MerkleTree([b"alice", b"bob", b"carol"])
+    >>> verify_proof(b"bob", tree.proof(1), tree.root)
+    True
+    """
+
+    def __init__(self, leaves: Iterable[bytes]) -> None:
+        payloads = tuple(leaves)
+        if any(not isinstance(leaf, bytes) for leaf in payloads):
+            raise TypeError("leaves must be bytes")
+        self._count = len(payloads)
+        level = tuple(sha256(MERKLE_LEAF_PREFIX + leaf) for leaf in payloads)
+        levels = [level]
+        while len(level) > 1:
+            level = tuple(
+                sha256(MERKLE_NODE_PREFIX + level[i] + level[i + 1])
+                if i + 1 < len(level)
+                else level[i]
+                for i in range(0, len(level), 2)
+            )
+            levels.append(level)
+        self._levels = tuple(levels)
+        self._root = _root(self._count, level[0] if level else b"")
+
+    def __repr__(self) -> str:
+        return f"MerkleTree(leaves={self._count}, root={self._root.hex()[:16]}...)"
+
+    @property
+    def root(self) -> bytes:
+        """Return the immutable 32-byte, leaf-count-bound root."""
+        return self._root
+
+    @property
+    def leaf_count(self) -> int:
+        """Return the number of leaves the root commits to."""
+        return self._count
+
+    def consistency_proof(self, old_size: int) -> tuple[bytes, ...]:
+        """Prove that this tree extends its first ``old_size`` leaves (RFC 6962)."""
+        return consistency_proof(self, old_size)
+
+    @property
+    def levels(self) -> tuple[tuple[bytes, ...], ...]:
+        """Return every level's digests, from leaf hashes up to the top digest.
+
+        The top digest is not yet the root: the root also binds the leaf count.
+        An empty tree has a single empty level.
+        """
+        return self._levels
+
+    def proof(self, index: int) -> MerkleProof:
+        """Return a logarithmic-size inclusion proof at a zero-based position."""
+        if type(index) is not int or not 0 <= index < self._count:
+            raise IndexError("leaf index out of range")
+        siblings = []
+        position = index
+        for level in self._levels[:-1]:
+            sibling = position ^ 1
+            siblings.append(level[sibling] if sibling < len(level) else None)
+            position //= 2
+        return MerkleProof(index, self._count, tuple(siblings))
+
+
+def _walk(leaf: bytes, proof: MerkleProof) -> tuple[bytes, list[ProofStep]] | None:
+    """Recompute the top digest bottom-up; return None for a malformed proof."""
+    if not isinstance(leaf, bytes) or not isinstance(proof, MerkleProof):
+        return None
+    if type(proof.leaf_count) is not int or not 0 < proof.leaf_count < UINT64_LIMIT:
+        return None
+    if type(proof.index) is not int or not 0 <= proof.index < proof.leaf_count:
+        return None
+    if not isinstance(proof.siblings, tuple):
+        return None
+    if len(proof.siblings) != (proof.leaf_count - 1).bit_length():
+        return None
+    leaf_digest = sha256(MERKLE_LEAF_PREFIX + leaf)
+    current, index, count = leaf_digest, proof.index, proof.leaf_count
+    steps = []
+    # The checked path length ensures count > 1 at every iteration, and
+    # repeated ceiling-halving reaches exactly 1 after the final sibling.
+    for sibling in proof.siblings:
+        if (index ^ 1) >= count:
+            if sibling is not None:
+                return None
+            side = "promoted"
+        else:
+            if not isinstance(sibling, bytes) or len(sibling) != 32:
+                return None
+            side = "left" if index % 2 else "right"
+            left, right = (sibling, current) if side == "left" else (current, sibling)
+            current = sha256(MERKLE_NODE_PREFIX + left + right)
+        steps.append(ProofStep(side, sibling, current))
+        index //= 2
+        count = (count + 1) // 2
+    return leaf_digest, steps
+
+
+def verify_proof(leaf: bytes, proof: MerkleProof, root: bytes) -> bool:
+    """Verify payload, position, shape, count, and root; reject malformed proofs."""
+    if not isinstance(root, bytes) or len(root) != 32:
+        return False
+    walked = _walk(leaf, proof)
+    if walked is None:
+        return False
+    leaf_digest, steps = walked
+    top = steps[-1].digest if steps else leaf_digest
+    return _root(proof.leaf_count, top) == root
+
+
+def trace_proof(leaf: bytes, proof: MerkleProof, root: bytes) -> MerkleTrace:
+    """Reconstruct the root step by step, recording each level.
+
+    Unlike :func:`verify_proof`, a well-formed proof that reconstructs the
+    wrong root still returns its full trace (with ``valid=False``), so an
+    experiment can show where a tampered leaf diverges.
+
+    Raises
+    ------
+    ValueError
+        The proof is malformed: wrong shape, count, index, or sibling type.
+
+    Examples
+    --------
+    >>> from blockchainkit.structures import MerkleTree, trace_proof
+    >>> tree = MerkleTree([b"a", b"b", b"c"])
+    >>> [step.side for step in trace_proof(b"c", tree.proof(2), tree.root).steps]
+    ['promoted', 'left']
+    """
+    walked = _walk(leaf, proof)
+    if walked is None:
+        raise ValueError("malformed Merkle proof")
+    leaf_digest, steps = walked
+    top = steps[-1].digest if steps else leaf_digest
+    computed = _root(proof.leaf_count, top)
+    return MerkleTrace(leaf_digest, tuple(steps), computed, computed == root)
+
+
+def _subtree(digests: list[bytes]) -> bytes:
+    """Top digest of consecutive leaf digests (the RFC 6962 tree shape)."""
+    if len(digests) == 1:
+        return digests[0]
+    split = 1 << ((len(digests) - 1).bit_length() - 1)  # Largest power of two below n.
+    return sha256(MERKLE_NODE_PREFIX + _subtree(digests[:split]) + _subtree(digests[split:]))
+
+
+def _subproof(m: int, digests: list[bytes], complete: bool) -> list[bytes]:
+    n = len(digests)
+    if m == n:
+        return [] if complete else [_subtree(digests)]
+    split = 1 << ((n - 1).bit_length() - 1)
+    if m <= split:
+        return _subproof(m, digests[:split], complete) + [_subtree(digests[split:])]
+    return _subproof(m - split, digests[split:], False) + [_subtree(digests[:split])]
+
+
+def consistency_proof(tree: MerkleTree, old_size: int) -> tuple[bytes, ...]:
+    """Prove that the first ``old_size`` leaves of ``tree`` form an earlier tree.
+
+    The proof (RFC 6962, section 2.1.2) lists the subtree digests needed to
+    rebuild both the old and the new top digest from shared parts, so a
+    verifier can check that the log only appended. Because blockchainkit's
+    roots also bind the leaf count, the verifier cannot read the old top
+    digest off the old root; when ``old_size`` is a power of two (the case
+    where RFC 6962 omits it) the proof starts with it. Also available as
+    :meth:`MerkleTree.consistency_proof`.
+    """
+    integer(old_size, "old_size", 1)
+    if old_size > tree.leaf_count:
+        raise ValueError("old_size cannot exceed the tree's leaf count")
+    digests = list(tree.levels[0])
+    if old_size == tree.leaf_count:
+        return ()
+    proof = _subproof(old_size, digests, True)
+    if old_size & (old_size - 1) == 0:
+        proof.insert(0, _subtree(digests[:old_size]))
+    return tuple(proof)
+
+
+def verify_consistency(
+    old_size: int, old_root: bytes, new_size: int, new_root: bytes, proof: tuple[bytes, ...]
+) -> bool:
+    """Check that the tree with ``old_root`` is a prefix of the tree with ``new_root``.
+
+    Follows RFC 9162, section 2.1.4.2, on top digests, then checks both
+    count-bound roots. Malformed or mismatched proofs return False.
+
+    Examples
+    --------
+    >>> from blockchainkit.structures import MerkleTree, verify_consistency
+    >>> leaves = [bytes([i]) for i in range(7)]
+    >>> old, new = MerkleTree(leaves[:3]), MerkleTree(leaves)
+    >>> verify_consistency(3, old.root, 7, new.root, new.consistency_proof(3))
+    True
+    """
+    if type(old_size) is not int or type(new_size) is not int or not 0 < old_size <= new_size:
+        return False
+    if any(not isinstance(digest, bytes) or len(digest) != 32 for digest in proof):
+        return False
+    if old_size == new_size:
+        return not proof and old_root == new_root
+    if not proof:
+        return False
+    fn, sn = old_size - 1, new_size - 1
+    while fn & 1:
+        fn, sn = fn >> 1, sn >> 1
+    old_top = new_top = proof[0]
+    for digest in proof[1:]:
+        if sn == 0:
+            return False
+        if fn & 1 or fn == sn:
+            old_top = sha256(MERKLE_NODE_PREFIX + digest + old_top)
+            new_top = sha256(MERKLE_NODE_PREFIX + digest + new_top)
+            while not fn & 1 and fn:
+                fn, sn = fn >> 1, sn >> 1
+        else:
+            new_top = sha256(MERKLE_NODE_PREFIX + new_top + digest)
+        fn, sn = fn >> 1, sn >> 1
+    return sn == 0 and _root(old_size, old_top) == old_root and _root(new_size, new_top) == new_root
+
+
+def bitcoin_merkle_root(leaves: Iterable[bytes]) -> bytes:
+    """Return a root in Bitcoin's convention: double SHA-256, odd nodes duplicated.
+
+    Shown for contrast with :class:`MerkleTree`. With no domain separation
+    and no leaf count, the lists ``[a, b, c]`` and ``[a, b, c, c]`` share a
+    root (CVE-2012-2459), which let an attacker make nodes reject a valid
+    block. :class:`MerkleTree` promotes odd nodes and binds the count instead.
+
+    >>> from blockchainkit.structures import bitcoin_merkle_root
+    >>> bitcoin_merkle_root([b"a", b"b", b"c"]) == bitcoin_merkle_root([b"a", b"b", b"c", b"c"])
+    True
+    """
+    level = [hash256(leaf) for leaf in leaves]
+    if not level:
+        raise ValueError("Bitcoin's convention has no root for an empty list")
+    while len(level) > 1:
+        if len(level) % 2:
+            level.append(level[-1])
+        level = [hash256(level[i] + level[i + 1]) for i in range(0, len(level), 2)]
+    return level[0]

blockchainkit/structures/systems/mmr.py

@@ -0,0 +1,112 @@
+"""Merkle mountain ranges (2016): an append-only log with cheap updates.
+
+A Merkle tree over n leaves is rebuilt along a whole path when a leaf is
+added. A mountain range keeps a list of perfect binary trees ("peaks") of
+decreasing size, one per 1-bit of n. Appending a leaf adds a peak of size
+one and merges equal-sized neighbours, like binary addition: on average a
+constant number of merges. Old peaks are never rewritten, so proofs about
+old leaves need only the peaks to be refreshed. The root "bags" the peaks.
+"""
+
+from blockchainkit.constants import MERKLE_LEAF_PREFIX, MERKLE_NODE_PREFIX, MMR_ROOT_PREFIX
+from blockchainkit.crypto.systems.hashing import sha256
+from blockchainkit.structures.core.base import MMRProof
+
+
+def _node(left: bytes, right: bytes) -> bytes:
+    return sha256(MERKLE_NODE_PREFIX + left + right)
+
+
+def _bag(size: int, peaks: tuple[bytes, ...]) -> bytes:
+    return sha256(MMR_ROOT_PREFIX + size.to_bytes(8, "big") + b"".join(peaks))
+
+
+def _peak_ranges(size: int) -> list[tuple[int, int]]:
+    """(start, leaf count) of each peak, largest first: the 1-bits of ``size``."""
+    ranges, start = [], 0
+    for bit in reversed(range(size.bit_length())):
+        if size >> bit & 1:
+            ranges.append((start, 1 << bit))
+            start += 1 << bit
+    return ranges
+
+
+class MerkleMountainRange:
+    """An immutable append-only accumulator of byte strings.
+
+    Examples
+    --------
+    >>> from blockchainkit.structures import MerkleMountainRange, verify_mmr_proof
+    >>> mmr = MerkleMountainRange()
+    >>> for leaf in (b"a", b"b", b"c"):
+    ...     mmr = mmr.append(leaf)
+    >>> len(mmr.peaks), verify_mmr_proof(b"c", mmr.proof(2), mmr.root)
+    (2, True)
+    """
+
+    def __init__(self) -> None:
+        self._leaves: tuple[bytes, ...] = ()
+        self._peaks: tuple[tuple[int, bytes], ...] = ()  # (leaf count, digest)
+
+    def __len__(self) -> int:
+        return len(self._leaves)
+
+    def __repr__(self) -> str:
+        return f"MerkleMountainRange(leaves={len(self)}, peaks={len(self._peaks)})"
+
+    def append(self, leaf: bytes) -> "MerkleMountainRange":
+        """Return a range with one more leaf, merging equal-sized peaks.
+
+        Only the new leaf's hash and the merged nodes are computed: about
+        two hashes per append on average, however long the range.
+        """
+        if not isinstance(leaf, bytes):
+            raise TypeError("leaves must be bytes")
+        peaks = [*self._peaks, (1, sha256(MERKLE_LEAF_PREFIX + leaf))]
+        while len(peaks) > 1 and peaks[-1][0] == peaks[-2][0]:
+            (count, left), (_, right) = peaks[-2], peaks[-1]
+            peaks[-2:] = [(2 * count, _node(left, right))]
+        grown = MerkleMountainRange()
+        grown._leaves, grown._peaks = (*self._leaves, leaf), tuple(peaks)
+        return grown
+
+    @property
+    def peaks(self) -> tuple[bytes, ...]:
+        """Peak digests, largest tree first; there is one per 1-bit of the size."""
+        return tuple(digest for _, digest in self._peaks)
+
+    @property
+    def root(self) -> bytes:
+        """Bag the peaks, with the size, into one commitment."""
+        return _bag(len(self), self.peaks)
+
+    def proof(self, index: int) -> MMRProof:
+        """Return an inclusion proof for the leaf at ``index``."""
+        if type(index) is not int or not 0 <= index < len(self):
+            raise IndexError("leaf index out of range")
+        start, count = next((s, n) for s, n in _peak_ranges(len(self)) if s <= index < s + n)
+        level = [sha256(MERKLE_LEAF_PREFIX + leaf) for leaf in self._leaves[start : start + count]]
+        position, siblings = index - start, []
+        while len(level) > 1:
+            siblings.append(level[position ^ 1])
+            level = [_node(level[i], level[i + 1]) for i in range(0, len(level), 2)]
+            position //= 2
+        return MMRProof(index, len(self), tuple(siblings), self.peaks)
+
+
+def verify_mmr_proof(leaf: bytes, proof: MMRProof, root: bytes) -> bool:
+    """Rebuild the leaf's peak, find it among the peaks, and check the bagged root."""
+    ranges = _peak_ranges(proof.size)
+    if len(proof.peaks) != len(ranges) or _bag(proof.size, proof.peaks) != root:
+        return False
+    found = [(i, s, n) for i, (s, n) in enumerate(ranges) if s <= proof.index < s + n]
+    if not found or not isinstance(leaf, bytes):
+        return False
+    peak_index, start, count = found[0]
+    if len(proof.siblings) != count.bit_length() - 1:
+        return False
+    current, position = sha256(MERKLE_LEAF_PREFIX + leaf), proof.index - start
+    for sibling in proof.siblings:
+        current = _node(sibling, current) if position & 1 else _node(current, sibling)
+        position //= 2
+    return current == proof.peaks[peak_index]

blockchainkit/structures/systems/sparse_merkle.py

@@ -0,0 +1,139 @@
+"""Sparse Merkle trees (2016): a key-value map with membership and non-membership proofs.
+
+Picture a Merkle tree with one leaf for every possible 256-bit key, almost
+all empty. Each key's position is fixed by its hash, so the root is
+independent of insertion order, and absence is provable: show that the leaf
+at the key's position is empty. Empty subtrees have precomputed default
+digests, so only paths to non-empty leaves are ever hashed.
+"""
+
+from functools import cache, cached_property
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import MERKLE_LEAF_PREFIX, MERKLE_NODE_PREFIX
+from blockchainkit.crypto.systems.hashing import sha256
+from blockchainkit.structures.core.base import SparseMerkleProof
+
+_EMPTY_LEAF = bytes(32)
+
+
+@cache
+def _default(height: int) -> bytes:
+    """Digest of an empty subtree of the given height."""
+    if height == 0:
+        return _EMPTY_LEAF
+    below = _default(height - 1)
+    return sha256(MERKLE_NODE_PREFIX + below + below)
+
+
+def _path(key: bytes, depth: int) -> int:
+    return int.from_bytes(sha256(key), "big") >> (256 - depth)
+
+
+def _leaf(key: bytes, value: bytes) -> bytes:
+    return sha256(MERKLE_LEAF_PREFIX + len(key).to_bytes(8, "big") + key + value)
+
+
+class SparseMerkleTree:
+    """An immutable map from byte keys to byte values with a Merkle root.
+
+    Parameters
+    ----------
+    depth : int
+        Number of key-hash bits used for the position, 1 to 256. A small
+        depth makes collisions between keys possible; it exists only to make
+        small experiments easy to draw.
+
+    Examples
+    --------
+    >>> from blockchainkit.structures import SparseMerkleTree, verify_sparse_proof
+    >>> tree = SparseMerkleTree().set(b"alice", b"100")
+    >>> verify_sparse_proof(tree.prove(b"bob"), tree.root)  # Proof that bob is absent.
+    True
+    """
+
+    def __init__(self, depth: int = 256, items: dict[bytes, bytes] | None = None) -> None:
+        integer(depth, "depth", 1)
+        if depth > 256:
+            raise ValueError("depth cannot exceed 256")
+        self._depth = depth
+        self._items = dict(items or {})
+        self._leaves = {_path(k, depth): _leaf(k, v) for k, v in self._items.items()}
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def __repr__(self) -> str:
+        root = self.root.hex()[:16]
+        return f"SparseMerkleTree(depth={self._depth}, keys={len(self)}, root={root}...)"
+
+    @staticmethod
+    def _check(key: bytes, value: bytes = b"") -> None:
+        if not isinstance(key, bytes) or not isinstance(value, bytes):
+            raise TypeError("keys and values must be bytes")
+
+    def get(self, key: bytes) -> bytes | None:
+        """Return the value stored at a key, or None."""
+        self._check(key)
+        return self._items.get(key)
+
+    def set(self, key: bytes, value: bytes) -> "SparseMerkleTree":
+        """Return a new tree with ``key`` mapped to ``value``."""
+        self._check(key, value)
+        return SparseMerkleTree(self._depth, {**self._items, key: value})
+
+    def delete(self, key: bytes) -> "SparseMerkleTree":
+        """Return a new tree without ``key``."""
+        self._check(key)
+        return SparseMerkleTree(self._depth, {k: v for k, v in self._items.items() if k != key})
+
+    def _digest(self, height: int, prefix: int, leaves: dict[int, bytes]) -> bytes:
+        """Digest of the subtree of ``height`` whose positions start with ``prefix``."""
+        if not leaves:
+            return _default(height)
+        if height == 0:
+            return leaves[prefix]
+        left_prefix, right_prefix = prefix << 1, (prefix << 1) | 1
+        shift = height - 1
+        left = {p: d for p, d in leaves.items() if p >> shift == left_prefix}
+        right = {p: d for p, d in leaves.items() if p >> shift == right_prefix}
+        return sha256(
+            MERKLE_NODE_PREFIX
+            + self._digest(shift, left_prefix, left)
+            + self._digest(shift, right_prefix, right)
+        )
+
+    @cached_property
+    def root(self) -> bytes:
+        """Return the root digest; equal maps give equal roots, in any order."""
+        return self._digest(self._depth, 0, self._leaves)
+
+    def prove(self, key: bytes) -> SparseMerkleProof:
+        """Return a proof of the key's value, or of its absence."""
+        self._check(key)
+        position = _path(key, self._depth)
+        siblings = []
+        for height in range(self._depth):
+            sibling_prefix = (position >> height) ^ 1
+            subtree = {p: d for p, d in self._leaves.items() if p >> height == sibling_prefix}
+            siblings.append(self._digest(height, sibling_prefix, subtree))
+        return SparseMerkleProof(key, self._items.get(key), tuple(siblings))
+
+
+def verify_sparse_proof(proof: SparseMerkleProof, root: bytes) -> bool:
+    """Recompute the root from a key, its claimed value (or absence), and siblings.
+
+    The number of siblings is the tree depth. Leaf and node digests carry
+    different prefixes, so a shorter proof cannot pass for a longer one.
+    """
+    depth = len(proof.siblings)
+    if not 1 <= depth <= 256 or any(not isinstance(d, bytes) for d in proof.siblings):
+        return False
+    position = _path(proof.key, depth)
+    current = _EMPTY_LEAF if proof.value is None else _leaf(proof.key, proof.value)
+    for height, sibling in enumerate(proof.siblings):
+        if (position >> height) & 1:
+            current = sha256(MERKLE_NODE_PREFIX + sibling + current)
+        else:
+            current = sha256(MERKLE_NODE_PREFIX + current + sibling)
+    return current == root

blockchainkit/structures/systems/transaction.py

@@ -0,0 +1,116 @@
+"""Immutable signed account transfers and deterministic teaching encodings."""
+
+from dataclasses import dataclass, replace
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import DEFAULT_CHAIN_ID, UINT64_LIMIT
+from blockchainkit.crypto import (
+    SchnorrSignature,
+    encode_point,
+    public_key,
+    sha256,
+    sign,
+    verify,
+)
+from blockchainkit.structures.utils.accounts import is_account_id
+from blockchainkit.structures.utils.encoding import canonical_json
+
+
+def address(public: tuple[int, int]) -> str:
+    """Return SHA-256(uncompressed public key) as a 64-character account ID."""
+    return sha256(encode_point(public)).hex()
+
+
+@dataclass(frozen=True)
+class Transaction:
+    """An integer-valued transfer, signed over network ID and account nonce.
+
+    Parameters
+    ----------
+    sender : tuple of int
+        secp256k1 public point.
+    recipient : str
+        Lowercase 64-character hexadecimal account identifier.
+    amount : int
+        Positive integer units (no floating-point currency amounts).
+    nonce : int
+        Sender sequence number, starting at zero.
+    chain_id : str
+        Domain that prevents replay onto a different teaching network.
+    signature : SchnorrSignature, optional
+        Signature over the canonical unsigned payload.
+    """
+
+    sender: tuple[int, int]
+    recipient: str
+    amount: int
+    nonce: int
+    chain_id: str = DEFAULT_CHAIN_ID
+    signature: SchnorrSignature | None = None
+
+    def __post_init__(self) -> None:
+        encode_point(self.sender)
+        if not is_account_id(self.recipient):
+            raise ValueError("recipient must be a lowercase SHA-256 account identifier")
+        integer(self.amount, "amount", 1)
+        integer(self.nonce, "nonce")
+        if self.amount >= UINT64_LIMIT or self.nonce >= UINT64_LIMIT:
+            raise ValueError("amount and nonce must fit unsigned 64-bit integers")
+        if not isinstance(self.chain_id, str) or not 1 <= len(self.chain_id) <= 128:
+            raise ValueError("chain_id must contain 1 to 128 characters")
+        if self.signature is not None and not isinstance(self.signature, SchnorrSignature):
+            raise TypeError("signature must be a SchnorrSignature or None")
+
+    @property
+    def sender_address(self) -> str:
+        """Return the account identifier derived from the sender's public key."""
+        return address(self.sender)
+
+    def payload(self) -> bytes:
+        """Return the exact bytes signed, including domain and format version."""
+        return canonical_json(
+            {
+                "version": 1,
+                "chain_id": self.chain_id,
+                "sender": encode_point(self.sender).hex(),
+                "recipient": self.recipient,
+                "amount": self.amount,
+                "nonce": self.nonce,
+            }
+        )
+
+    def to_bytes(self) -> bytes:
+        """Serialize the unsigned payload and signature without ambiguity."""
+        signature = None
+        if self.signature is not None:
+            signature = [list(self.signature.commitment), self.signature.response]
+        return canonical_json({"payload": self.payload().decode(), "signature": signature})
+
+    @property
+    def txid(self) -> bytes:
+        """Return a digest of the signed transaction encoding.
+
+        Because it covers the signature, re-signing the same payment changes
+        it: the malleability that segregated witness removed from Bitcoin's
+        transaction ids. Compare :attr:`unsigned_id`.
+        """
+        return sha256(self.to_bytes())
+
+    @property
+    def unsigned_id(self) -> bytes:
+        """Return a digest of the unsigned payload only, as SegWit's txid does.
+
+        Any valid signature over the same payment gives the same value, so a
+        later transaction can refer to this one before it is confirmed.
+        """
+        return sha256(self.payload())
+
+    def is_valid(self) -> bool:
+        """Check the signature; account balance and nonce are checked by Ledger."""
+        return self.signature is not None and verify(self.payload(), self.signature, self.sender)
+
+    def signed(self, private: int, *, signing_nonce: int | None = None) -> "Transaction":
+        """Return a signed copy, checking that the key matches this sender."""
+        if public_key(private) != self.sender:
+            raise ValueError("private key does not match sender")
+        return replace(self, signature=sign(self.payload(), private, nonce=signing_nonce))