Blockchain Foundations — Cryptography

Educational Python library demonstrating SHA-256 and binary Merkle trees with inclusion proofs. Built with Spec-Driven Development; normative behavior lives in docs/spec/.

Features

• SHA-256 wrappers with domain-separated leaf and node hashing
• Merkle tree construction, root commitment, and inclusion proof generation/verification
• Comprehensive tests pinned to spec test vectors

Quick start

python -m pip install -e ".[dev]"
pytest -q

from crypto_foundations import MerkleTree, verify_merkle_proof, hash_leaf

leaves = [b"tx0", b"tx1", b"tx2", b"tx3"]
tree = MerkleTree(leaves)

print("root:", tree.root_hex)

proof = tree.get_proof(2)
ok = verify_merkle_proof(b"tx2", proof, tree.root)
print("proof valid:", ok)

Differences from Bitcoin

This project prioritizes clarity for learning. It is not byte-compatible with Bitcoin Core’s transaction Merkle tree:

Topic	This library	Bitcoin
Leaf hash	SHA256(b"leaf:" || payload)	Double SHA-256 of txid
Internal node	SHA256(b"node:" || left || right)	Double SHA-256 of children
Odd leaf count	Duplicate last node at each level	CVE-2012-2459 mitigation rule

See docs/spec/02-merkle-tree.md § 10.

Project layout

src/crypto_foundations/   # hash.py, merkle.py
tests/                    # pytest suite
docs/spec/                # normative specifications

Specifications

Document	Content
00-overview.md	Scope and release criteria
01-hash.md	Hash API and vectors
02-merkle-tree.md	Merkle API, proofs, tests

License

MIT — see LICENSE.