blockchainkit

Cryptography and blockchains, understood through experiments.

blockchainkit is a teaching toolkit spanning 5 subpackages, from public-key cryptography to replicated execution, under one small typed API. Start with two people agreeing on a secret. Follow the ideas that make it possible to prove knowledge, authenticate a payment, commit to a history, compare competing histories, and execute a shared program. Each step links an explanation to working Python, a figure, and an experiment you can change.

The history is the spine of the package. Each subpackage’s history page traces the breakthroughs behind it and their limitations, from Diffie-Hellman to Ethereum, each linked to the code and the gallery example that reproduce it. Cryptography is central even though it is not in the package name.

Important

This is teaching software, not hardened cryptography or a node compatible with an existing blockchain. Tiny RSA and Diffie-Hellman parameters and variable-time curve arithmetic keep the mathematics visible; the Schnorr scheme is not BIP-340, and blocks are not Bitcoin or Ethereum wire formats. Exact conventions and model boundaries states every such choice precisely. For real systems, use audited libraries such as cryptography or libsecp256k1.

• blockchainkit.crypto: hashing and commitments, Diffie-Hellman and RSA, blind signatures, Shamir secret sharing, elliptic curves, and Schnorr proofs and signatures.

• blockchainkit.structures: Merkle trees and proofs, signed transfers, blocks, ledger state, and cumulative-work fork selection.

• blockchainkit.consensus: proof-of-work search and its expected cost, catch-up probabilities, and stake-weighted proposer selection.

• blockchainkit.network: peer graphs, Lamport and vector clocks, epidemic gossip and Byzantine reliable broadcast, the CAP trade-off, Kademlia with its Sybil and eclipse attacks, block relay, forks, and transaction privacy.

• blockchainkit.vm: a deterministic 256-bit stack machine with gas, traces and atomic failure; its assembler, expression compiler and bytecode verifier; Turing machines and busy beavers; Bitcoin Script with P2PKH and HTLCs; and smart contracts with the reentrancy and overflow attacks.

blockchainkit is part of a family of packages, with physicskit, mathematicskit and chemistrykit, that share the same architecture, API conventions, and history-driven documentation.

Choose a route

• New to the topic? Begin with Start here: a blockchain without the jargon. It explains the ideas using one imaginary payment, without assuming cryptography or finance knowledge. Keep the Glossary nearby.

• Learn in order: follow the A guided course: from fingerprints to shared history, with Exercises to check your reasoning.

• Learn the ideas: read the history, then run each linked experiment.

• Build a chain: follow Your first payment, step by step and the end-to-end payment experiment.

• Run simulations: read Reproducible experiments and research scope for assumptions and reproducibility.

Install and try it

pip install blockchainkit

import blockchainkit loads only the standard library. Matplotlib and NumPy are installed with the package for each subpackage’s plotting helpers in visualizers. Every gallery example can be downloaded as a script or a notebook.

Conventionally imported as bk:

import blockchainkit as bk

alice = bk.crypto.public_key(7)
signature = bk.crypto.sign(b"pay Bob 25", 7, nonce=11)
print(bk.crypto.verify(b"pay Bob 25", signature, alice))  # True