blockchainkit

Quality
Documentation
Code style
Try it online

Cryptography and blockchains, understood through experiments. blockchainkit is a Python toolkit for learning and teaching how blockchains work, from the one-time pad to Ethereum's gas. Each idea is followed from its history and mathematics to a small, typed, inspectable implementation, a figure, and an experiment you can change. Every subpackage's documentation walks through the field's breakthroughs in historical order, 87 of them in all, each linked to the code and the gallery example that reproduce it.

• For students: recover a private key from a reused signing nonce, find hash collisions at the birthday bound, watch a fork undo a payment, mine selfishly, eclipse a node, and drain a DAO-style contract, in a few lines each.
• For instructors: five subpackages, one consistent API, 88 gallery examples (each downloadable as a notebook or runnable in the browser), exercise pages with worked solutions, and cross-cutting tutorials.
• Honest about its limits: tiny keys, variable-time arithmetic and simplified formats keep the mathematics visible. Every adaptation is marked on its history entry and specified in the model boundaries. This is teaching software, not a wallet or a node.

import blockchainkit loads only the standard library. Matplotlib and NumPy are used only by each subpackage's visualizers.

pip install blockchainkit   # Python 3.10+

Conventionally imported as bk:

import blockchainkit as bk

alice_key = 7  # A fixed teaching key: never use such a key for real money.
alice = bk.structures.address(bk.crypto.public_key(alice_key))
bob = bk.structures.address(bk.crypto.public_key(11))

payment = bk.structures.Transaction(bk.crypto.public_key(alice_key), bob, 25, 0)
payment = payment.signed(alice_key, signing_nonce=17)  # Never reuse a signing nonce.

genesis = bk.consensus.mine(bk.structures.Block(difficulty=5)).block
chain = bk.structures.Blockchain(genesis, bk.structures.Ledger({alice: 100}))
block = bk.structures.Block(genesis.hash, (payment,), height=1, timestamp=1, difficulty=5)
chain.add(bk.consensus.mine(block).block)
assert chain.state.balances[bob] == 25

The quickstart notebook takes one payment from a signature to a mined block in about ten minutes. Open it in Colab using the badge above.

Subpackages

• blockchainkit.crypto -- the one-time pad, baby-step giant-step and Pohlig-Hellman, Merkle's puzzles, Diffie-Hellman and RSA, Shamir and Feldman secret sharing, Lamport signatures, birthday attacks, commitments (hash and Pedersen), blind signatures, elliptic curves, zero knowledge and Fiat-Shamir, Merkle-Damgård and length extension, HMAC, Schnorr signatures, RFC 6979 nonces, and MuSig. 22 breakthroughs.

  

• blockchainkit.structures -- double-entry ledgers, Bloom filters, Merkle trees and proofs, hash chains, linked and batched timestamps, the UTXO and account models, light clients, Bitcoin's duplicated-leaf bug, Certificate Transparency consistency proofs, transaction malleability, Merkle mountain ranges, replay protection, sparse Merkle trees, and blocks with cumulative-work fork choice. 15 breakthroughs.

  

• blockchainkit.consensus -- the gambler's ruin, Byzantine generals, Ben-Or and FLP, partial synchrony, PBFT, pricing functions and Hashcash, Nakamoto consensus and its double-spend calculation, difficulty retargeting, GHOST, selfish mining, proof of stake, nothing at stake, Casper FFG, and cryptographic sortition. 17 breakthroughs.

  

• blockchainkit.network -- discrete-event gossip, random, small-world and scale-free graphs, Lamport and vector clocks, epidemic rumor spreading, Bracha's reliable broadcast, CAP, Kademlia, Sybil and eclipse attacks, inv/getdata relay, propagation and forks, compact blocks, and Dandelion. 17 breakthroughs.

  

• blockchainkit.vm -- a deterministic 256-bit stack machine with gas and atomic failure, reverse Polish notation, Turing machines and the busy beaver, structured programming, Forth, state-machine replication, smart contracts, bytecode verification, Bitcoin Script with P2PKH and hash time-locked contracts, gas repricing, the DAO's reentrancy, and integer overflow. 16 breakthroughs.

  

Learn

• Start here: the ideas, with one imaginary payment and no prerequisites.
• Guided course: seven lessons in prerequisite order.
• Tutorials across subpackages: life of a payment, nonces everywhere, hashes everywhere, and who do you trust?
• Exercises: worked solutions, checked by every documentation build.
• History: the breakthroughs, each with plain-language explanation, mathematics, primary references, and its own experiment.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest --cov=blockchainkit --cov-branch          # 100% statement and branch coverage, enforced
pytest --doctest-modules blockchainkit --ignore-glob="*/tests/*"
ruff check . && ruff format --check .
mypy                                              # strict
cd docs && MPLBACKEND=Agg make html && MPLBACKEND=Agg make doctest

The documentation build runs every gallery example and every code line in the tutorials and exercise solutions, and treats warnings as errors. The README figures are regenerated with python docs/make_readme_figure.py and python docs/make_readme_subpackage_figures.py. See CONTRIBUTING.md.

blockchainkit belongs to a family of teaching toolkits with the same architecture: mathematicskit, physicskit and chemistrykit.

MIT license; see LICENSE. To cite blockchainkit, see CITATION.cff.