blockchainkit

Package
Quality
Documentation
Code style
Downloads
Community
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, 120 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, drain a DAO-style contract, take over a Parity wallet, and sandwich a swap, in a few lines each.
• For instructors: seven subpackages, one consistent API, 121 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.

  

• blockchainkit.contracts -- a world-state model of contracts calling contracts, with Floyd-Hoare proofs, symbolic execution, design by contract, Ricardian contracts, capabilities and tx.origin, ERC-20 and its approval race, unchecked sends, gas denial of service, commit-reveal randomness, the two Parity wallet incidents, ERC-721, proxy storage collisions, CREATE2, Oyente and Echidna, and Beanstalk's flash-loan governance attack. 17 breakthroughs.

  

• blockchainkit.economics -- incentives, fees and markets: Schelling's focal points and SchellingCoin, Vickrey's and Myerson's auctions, Hanson's market scoring rule, block rewards and the halving, Bitcoin without the subsidy, mining games, EIP-1559, Dai and liquidation, Uniswap and impermanent loss, flash-loan oracle manipulation, priority gas auctions, sandwich attacks, and proposer-builder separation. 16 breakthroughs.

  

• blockchainkit.channels -- layer-2 scaling and interoperability: Reed-Solomon codes, Spilman's and duplex channels, Lightning's revocation, Sprites and state channels, eltoo, watchtowers, balance probing, atomic swaps, BTC Relay, the Ronin and Wormhole exploits, Plasma, OmniLedger sharding, zk and optimistic rollups, and data-availability sampling. 16 breakthroughs.

  

• blockchainkit.proofs -- zero-knowledge and succinct proofs: the Schwartz-Zippel lemma, sum-check, IP = PSPACE, the PCP theorem, Kilian's and Micali's arguments, KZG commitments, QAPs and Pinocchio, Zerocash, Groth16, trusted-setup ceremonies, Bulletproofs, FRI, STARKs, PLONK, and Halo. 16 breakthroughs.

  

• blockchainkit.fraud -- financial fraud on and around blockchains: Ponzi's scheme, Benford's law, Maxwell's proof of reserves, Mt. Gox and the malleability excuse, Provisions, deceptive verified sources, Ethereum's Ponzi contracts, ICO exit scams and the DAICO, the Willy bot, BitConnect, honeypots, pump-and-dumps, the Squid Game rug pull, NFT wash trading, ice phishing, FTX, and address poisoning. 17 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.