blockchainkit 0.2.0__tar.gz

blockchainkit-0.2.0/CHANGELOG.md

@@ -0,0 +1,148 @@
+# Changelog
+
+## [0.2.0] - 2026-10-04
+
+The package is aligned with its kit-family siblings, and every subpackage now
+follows its field through at least 15 breakthroughs, each with its own
+experiment.
+
+### Added
+
+- Tutorials across subpackages, every line run by the doctest build: *Life of
+  a payment*, *Nonces everywhere*, *Hashes everywhere* and *Who do you
+  trust?*.
+- Exercise pages, one per subpackage, with 40 worked solutions in collapsed
+  boxes, each run by the doctest build. They replace the single solutions page.
+- A "Teaching vs production" note on every history entry that adapts a
+  deployed protocol, naming the difference.
+- README figures, regenerated by `docs/make_readme_figure.py` and
+  `docs/make_readme_subpackage_figures.py`.
+- Execution history: 16 breakthroughs, each with its own gallery example,
+  from reverse Polish notation (1924-1957) to the BeautyChain overflow
+  (2018). New APIs: `execute(..., arguments=...)`, the Forth words `OVER` and
+  `ROT`, `REVERT`, and the shared `STACK_EFFECTS` table; `validate_program`;
+  `assemble` (labels); `to_rpn` and `compile_expression`; `verify_bytecode`
+  and `VerificationResult`; `run_turing_machine`, `enumerate_machines` and
+  `busy_beaver` (reproducing S(2) = 6); Bitcoin-style Script with
+  `verify_script`, `p2pkh_locking`/`p2pkh_unlocking` and `htlc_locking`
+  (`OP_CHECKLOCKTIMEVERIFY`); the contracts `vending_machine` and
+  `batch_transfer` (BEC overflow, with a SafeMath option); `drain_bank`
+  (DAO reentrancy); and the plot `plot_stack_height`.
+- Network history: 17 breakthroughs, each with its own gallery example, from
+  Erdős-Rényi random graphs (1959) to Dandelion (2017). New APIs: `Graph`,
+  `erdos_renyi`, `ring_lattice`, `watts_strogatz`, `barabasi_albert` and
+  `complete_graph`; `lamport_timestamps`, `vector_timestamps`,
+  `happened_before` and `concurrent`; `spread_rumor` (push, pull, push-pull)
+  and `pittel_rounds`; `reliable_broadcast` (Bracha); `ReplicatedRegister`
+  (CAP); `KademliaNetwork`, `xor_distance` and `node_id`; `AddressManager`
+  and `eclipse_probability`; `relay_cost`, `compact_block_relay` and
+  `short_id`; `fork_rate` and `simulate_fork_rate`; `first_spy_precision`;
+  `SimulatedNetwork.from_graph` and `SimulatedNetwork.messages_sent`; the
+  plots `plot_graph`, `plot_space_time` and `plot_rumor_spread`; and the
+  `COMPACT_BLOCK_DOMAIN` constant.
+- Consensus history: 17 breakthroughs, each with its own gallery example,
+  from the gambler's ruin (1656) to Casper FFG (2017). New APIs:
+  `oral_messages` (Byzantine generals); `ben_or` (randomized consensus, also
+  used to show the FLP adversary); `view_changes` (partial synchrony);
+  `modular_square_root` (Dwork-Naor pricing); `pbft_round` and
+  `quorum_size`; `attacker_success_probability` (whitepaper section 11, checked
+  against its table); `retarget` and `simulate_difficulty`; `ghost_tip` and
+  `subtree_work`; `selfish_mining_revenue`, `selfish_mining_threshold` and
+  `simulate_selfish_mining`; `fork_voting_payoffs` (nothing at stake);
+  `sortition`; and `FinalityGadget` (Casper FFG with slashing detection).
+- Structures history: 15 breakthroughs, each with its own gallery example,
+  from double-entry bookkeeping (1494) to Merkle mountain ranges (2016). New
+  APIs: `Ledger.total_supply`; `BloomFilter`; `hash_chain` and
+  `verify_one_time_password`; `BlockHeader`, `Block.to_header()` and
+  `verify_header_chain` for light clients; `bitcoin_merkle_root` (Bitcoin's
+  duplicated-leaf convention, for CVE-2012-2459); `MerkleTree.consistency_proof`
+  and `verify_consistency` (RFC 6962/9162); `UTXOSet`, `UTXOTransaction`,
+  `OutPoint` and `Coin`; `Transaction.unsigned_id` (SegWit-style);
+  `SparseMerkleTree` with membership and non-membership proofs; and
+  `MerkleMountainRange`.
+- Cryptography history: 22 breakthroughs, each with its own gallery example,
+  from the one-time pad (1917-1949) to MuSig (2018). New APIs behind them:
+  `one_time_pad`/`xor_bytes`; `baby_step_giant_step` and `pohlig_hellman`;
+  `merkle_puzzles`/`solve_puzzle`; `lamport_keypair`/`lamport_sign`/
+  `lamport_verify`; `find_collision`/`truncated_hash`; a readable
+  Merkle-Damgard SHA-256 (`merkle_damgard_sha256`, `sha256_compress`,
+  `sha256_padding`) with `length_extension`; `naive_mac` and `hmac_sha256`;
+  `pedersen_commit`/`pedersen_generators`; `feldman_split`/`feldman_verify`;
+  `TEACHING_GROUP`, a 62-bit safe-prime group; `simulate_transcript`;
+  `deterministic_nonce` (RFC 6979, checked against the RFC's vectors); and
+  `musig_coefficients`/`aggregate_public_keys`/`musig_sign`.
+- `visualizers/` in every subpackage (Matplotlib, imported explicitly; plain
+  `import blockchainkit` still loads only the standard library):
+  `plot_curve_points`, `plot_hamming_distances`, `plot_merkle_tree`,
+  `plot_proof_trace`, `plot_block_tree`, `plot_mining_trials`,
+  `plot_stake_shares`, `plot_gossip_timeline`, `plot_execution_trace`.
+  Matplotlib and NumPy are now runtime dependencies; the `examples` extra is
+  gone.
+- `execute(..., trace=True)` records a `TraceStep` after every instruction,
+  following jumps; a failed run carries its partial trace in `VMError.trace`.
+  `execute(..., gas_costs=...)` prices opcodes individually (each at least 1).
+- `MerkleTree.levels`, `MerkleTree.leaf_count`, and `trace_proof`, which
+  returns a `MerkleTrace` of `ProofStep`s, even for a proof that fails.
+- `Blockchain.blocks`, `tips()`, `work_at()` and `state_at()` to inspect
+  side forks.
+- `enumerate_points` lists every point of a small curve.
+
+### Changed
+
+- The documentation follows the kit-family structure: generated hub pages per
+  subpackage, per-subpackage API pages, a `history/` directory with one
+  breakthroughs page per subpackage (each entry with its own *References:*
+  line and `minigallery`), an examples index, tutorials (the guided course and
+  solutions), and JupyterLite launch buttons. Examples moved to
+  `examples/<subpackage>/<topic>/`. The committed per-example notebooks and
+  their sync scripts are replaced by sphinx-gallery downloads and a single
+  `notebooks/quickstart.ipynb`.
+- The package uses the kit-family layout: one subpackage per domain with
+  `core/`, `systems/`, `utils/` and `tests/`, shared validation in
+  `_validation.py`, and every consensus-relevant constant in `constants.py`.
+  Public `bk.<subpackage>.<name>` imports are unchanged.
+- A wrong argument *type* (bool, float, string) now raises `TypeError`; an
+  out-of-range integer still raises `ValueError`. `multiply` reports the two
+  cases separately.
+- Mining varies only the header nonce: `Block.merkle_root` and `Block.hash`
+  are cached, and `Block.header(nonce=...)` builds a candidate header without
+  rebuilding the Merkle tree. Mining a 20-transaction block is about 59 times
+  faster per attempt (2 µs instead of 118 µs).
+- `verify` skips the subgroup-membership multiplications when Hasse's bound
+  proves the cofactor is 1 (new `Curve.cofactor_is_one`), halving the cost of
+  verification on secp256k1.
+- `Ledger`, `Blockchain`, `MerkleTree` and `SimulatedNetwork` have readable
+  `repr`s.
+
+### Fixed
+
+- `Transaction` rejects a `signature` that is not a `SchnorrSignature`;
+  before, the block hash raised `AttributeError` later.
+- `execute` raises `VMError`, not `TypeError`, for a non-string opcode.
+- `Curve` accepts secp256k1's field prime and group order only in their own
+  roles; swapping them no longer skips the primality check.
+- A receive callback that raises no longer leaves the payload marked seen.
+- `eventual_catch_up` rejects non-numeric fractions, and `StakeSampler` and
+  `SimulatedNetwork` reject non-integer seeds.
+
+## [0.1.0] - 2026-10-04
+
+Initial local release, never published.
+
+- Five typed subpackages for cryptography, authenticated structures, consensus
+  experiments, peer simulation, and bounded execution.
+- Sphinx history chapter covering 15 milestones with primary references.
+- Twelve executable gallery experiments and matching generated notebooks.
+- Signed account transfers, replay checks, atomic ledger updates, and fork
+  state restoration through cumulative-work chain selection.
+- Explicit teaching scope and package-specific serialization conventions.
+
+- Full statement and branch coverage, with 112 tests and a 100% coverage gate.
+- Stake sampling uses cumulative integer weights and binary search; Merkle proof
+  validation removes a redundant guard already implied by the checked path length.
+
+- Guided seven-lesson course with learning objectives, prerequisites, checkpoints,
+  and executable worked answers for all thirteen experiments.
+- Payment-lifecycle capstone with local pending queues, partitioned mining,
+  synchronization, reorganization, reinclusion, and replay rejection.
+- Merkle-proof and VM stack trace figures; historical overview and dependency map.

blockchainkit-0.2.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use blockchainkit in your research or teaching, please cite it as below."
+title: "blockchainkit: cryptography and blockchain breakthroughs, explained through reproducible Python experiments"
+type: software
+version: 0.2.0
+# Add `doi:` with this release's own Zenodo version DOI (not the concept DOI)
+# once the first release is archived.
+license: MIT
+repository-code: "https://github.com/cpoli/blockchainkit"
+url: "https://cpoli.github.io/blockchainkit/"
+authors:
+  - given-names: "Charles"
+    family-names: "Poli"
+    email: "cpoli374@gmail.com"
+keywords:
+  - blockchain
+  - cryptography
+  - education
+  - simulation
+  - consensus

blockchainkit-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,66 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in
+our community a harassment-free experience for everyone, regardless of
+age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open,
+welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our
+  mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political
+  attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our
+standards of acceptable behavior and will take appropriate and fair
+corrective action in response to any behavior that they deem
+inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces (issues, pull
+requests, discussions), and also applies when an individual is officially
+representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may
+be reported to the project maintainers by opening a confidential report
+via GitHub (see [SECURITY.md](SECURITY.md) for the equivalent private
+reporting channel). All complaints will be reviewed and investigated
+promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

blockchainkit-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing
+
+Keep the teaching chain intact: historical motivation, mathematical mechanism,
+typed public API, checked example, and explicit model assumptions.
+
+blockchainkit is organized as one subpackage per domain
+(`blockchainkit/<name>/`), each with its own `core/` (shared types and result
+dataclasses), `systems/` (concrete constructions and protocols, one module per
+family), `utils/` (supporting helpers that are not a model themselves), and
+`tests/` directory. Code shared by every subpackage lives at the top level:
+argument validation in `_validation.py` and every consensus-relevant constant
+(hash domain tags, encoding bounds, the default chain ID) in `constants.py`.
+New material belongs in the subpackage it fits best, re-exported from that
+subpackage's `__init__.py`.
+
+## Setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+pre-commit install
+```
+
+## Required checks
+
+```bash
+ruff check .
+ruff format --check .
+mypy
+pytest --cov=blockchainkit --cov-branch --cov-report=term-missing
+pytest --doctest-modules blockchainkit --ignore-glob="*/tests/*"
+cd docs && MPLBACKEND=Agg make html && MPLBACKEND=Agg make doctest && cd ..
+python -m build
+```
+
+Coverage runs must reach 100% for statements and branches across all package
+modules. `pyproject.toml` enforces this threshold for the CI coverage command.
+Add meaningful boundary and failure tests; do not exclude code to meet the target.
+
+The tests check independent vectors (SHA-256 test vectors, hand-computed curve
+points), algebraic identities (Diffie-Hellman agreement, RSA and blinding
+round-trips, Shamir reconstruction from every threshold subset), and failure
+behavior (signature tampering, nonce reuse, malformed Merkle proofs, replayed
+or overdrawn transfers, fork state restoration, VM resource limits). Passing
+them shows the teaching models behave as documented; it is not a
+cryptographic security audit.
+
+## History is part of the implementation
+
+`docs/source/history/` is a first-class deliverable: one page per subpackage,
+`<subpackage>_breakthroughs.rst`. A new entry must cite a primary source in a
+*References:* line, explain the original problem, give the key equation or
+mechanism, link to a concrete public API, and link its own gallery example(s)
+with `.. minigallery::`. No example is shared between two breakthroughs, and
+each example's title names its breakthrough. Distinguish original protocols
+from teaching adaptations. Do not describe a proposed future feature as an
+implemented breakthrough.
+
+Every public algorithm should have a clear docstring and type annotations.
+Use NumPy-style parameter/return sections where they clarify the interface.
+Tests should compare independent vectors, algebraic properties, conservation
+laws, or failure behavior rather than merely asserting the function returns.
+
+## Examples
+
+Examples live in `examples/<subpackage>/<topic>/plot_NN_<name>.py`, and each
+topic folder has a `README.rst` header. Sphinx-Gallery runs every script during
+the docs build and offers each one as a downloadable notebook and a JupyterLite
+launch, so the script is the single source of truth. Separate explanation and
+code with `# %%` cells. Use fixed simulation seeds, small bounded searches,
+assertions of the expected result, a "What to look for" section, and an
+exercise. Plot with the subpackage's `visualizers` where one fits.
+
+## Protocol changes
+
+Changing hash domains, serialization, validation, or tie-breaking can change
+consensus behavior. Update `docs/source/protocol.rst`, the relevant tests,
+examples, and changelog together. Reproducibility is scoped to recorded inputs
+and runtime versions; it is not a substitute for cryptographic randomness.

blockchainkit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Poli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blockchainkit-0.2.0/MANIFEST.in

@@ -0,0 +1,9 @@
+# The sdist carries the full test suite (each subpackage's tests/) for
+# downstream packagers; the wheel does not, via exclude-package-data in
+# pyproject.toml.
+graft blockchainkit
+include conftest.py
+include LICENSE README.md CONTRIBUTING.md CHANGELOG.md CITATION.cff CODE_OF_CONDUCT.md SECURITY.md ROADMAP.md
+recursive-include examples *.py *.rst
+include notebooks/quickstart.ipynb
+global-exclude __pycache__ *.py[cod] .DS_Store

blockchainkit-0.2.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: blockchainkit
+Version: 0.2.0
+Summary: Cryptography and blockchain breakthroughs, explained through reproducible Python experiments.
+Author-email: Charles Poli <cpoli374@gmail.com>
+Maintainer-email: Charles Poli <cpoli374@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cpoli/blockchainkit
+Project-URL: Issues, https://github.com/cpoli/blockchainkit/issues
+Project-URL: Changelog, https://github.com/cpoli/blockchainkit/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://cpoli.github.io/blockchainkit/
+Keywords: blockchain,cryptography,education,simulation,consensus,merkle-tree,proof-of-work,proof-of-stake,elliptic-curves,digital-signatures,gossip-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Classifier: Topic :: Education
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: numpy>=1.24
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov>=4; extra == "test"
+Requires-Dist: hypothesis>=6; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
+Requires-Dist: sphinx-gallery>=0.17; extra == "docs"
+Requires-Dist: sphinx-design>=0.6; extra == "docs"
+Requires-Dist: myst-parser>=2; extra == "docs"
+Requires-Dist: jupyterlite-sphinx>=0.17; extra == "docs"
+Requires-Dist: jupyterlite-pyodide-kernel>=0.4; extra == "docs"
+Requires-Dist: pillow>=9; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: blockchainkit[docs,test]; extra == "dev"
+Requires-Dist: ruff==0.16.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Dynamic: license-file
+
+# blockchainkit
+
+| | |
+|:--|:-:|
+| Quality | [![License](https://img.shields.io/github/license/cpoli/blockchainkit)](https://github.com/cpoli/blockchainkit/blob/main/LICENSE) [![CI](https://github.com/cpoli/blockchainkit/actions/workflows/ci.yml/badge.svg)](https://github.com/cpoli/blockchainkit/actions/workflows/ci.yml) [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](#development) |
+| Documentation | [![Docs](https://img.shields.io/badge/docs-cpoli.github.io%2Fblockchainkit-blue)](https://cpoli.github.io/blockchainkit/) |
+| Code style | [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
+| Try it online | [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/cpoli/blockchainkit/blob/main/notebooks/quickstart.ipynb) [![JupyterLite](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://cpoli.github.io/blockchainkit/lite/lab/) |
+
+**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.
+
+![A Merkle proof, Nakamoto's double-spend probabilities, and a Lamport space-time diagram, all drawn with blockchainkit](https://raw.githubusercontent.com/cpoli/blockchainkit/main/docs/source/_static/images/readme_hero.png)
+
+- **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](https://cpoli.github.io/blockchainkit/protocol.html).
+  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`.
+
+```bash
+pip install blockchainkit   # Python 3.10+
+```
+
+Conventionally imported as `bk`:
+
+```python
+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](https://github.com/cpoli/blockchainkit/blob/main/notebooks/quickstart.ipynb)
+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`](https://cpoli.github.io/blockchainkit/api/gallery/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.
+
+  ![Scalar multiples on an elliptic curve, the SHA-256 avalanche, and the birthday bound](https://raw.githubusercontent.com/cpoli/blockchainkit/main/docs/source/_static/images/readme_crypto.png)
+
+- [`blockchainkit.structures`](https://cpoli.github.io/blockchainkit/api/gallery/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.
+
+  ![A Merkle proof, a fork in a block tree, and Bloom-filter false-positive rates](https://raw.githubusercontent.com/cpoli/blockchainkit/main/docs/source/_static/images/readme_structures.png)
+
+- [`blockchainkit.consensus`](https://cpoli.github.io/blockchainkit/api/gallery/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.
+
+  ![Double-spend probabilities, selfish-mining revenue, and difficulty retargeting](https://raw.githubusercontent.com/cpoli/blockchainkit/main/docs/source/_static/images/readme_consensus.png)
+
+- [`blockchainkit.network`](https://cpoli.github.io/blockchainkit/api/gallery/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.
+
+  ![A small-world graph, push and pull gossip, and Kademlia lookup hops](https://raw.githubusercontent.com/cpoli/blockchainkit/main/docs/source/_static/images/readme_network.png)
+
+- [`blockchainkit.vm`](https://cpoli.github.io/blockchainkit/api/gallery/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.
+
+  ![Stack height of two expressions, halting times of two-state Turing machines, and a reentrancy attack](https://raw.githubusercontent.com/cpoli/blockchainkit/main/docs/source/_static/images/readme_vm.png)
+
+## Learn
+
+- [Start here](https://cpoli.github.io/blockchainkit/start_here.html): the ideas, with one imaginary
+  payment and no prerequisites.
+- [Guided course](https://cpoli.github.io/blockchainkit/tutorials/course.html): seven lessons in
+  prerequisite order.
+- Tutorials across subpackages: [life of a payment](https://cpoli.github.io/blockchainkit/tutorials/life_of_a_payment.html),
+  [nonces everywhere](https://cpoli.github.io/blockchainkit/tutorials/nonces_everywhere.html),
+  [hashes everywhere](https://cpoli.github.io/blockchainkit/tutorials/hashes_everywhere.html), and
+  [who do you trust?](https://cpoli.github.io/blockchainkit/tutorials/who_do_you_trust.html)
+- [Exercises](https://cpoli.github.io/blockchainkit/exercises/index.html): worked solutions, checked by
+  every documentation build.
+- [History](https://cpoli.github.io/blockchainkit/history/index.html): the breakthroughs, each with
+  plain-language explanation, mathematics, primary references, and its own experiment.
+
+## Development
+
+```bash
+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](CONTRIBUTING.md).
+
+blockchainkit belongs to a family of teaching toolkits with the same
+architecture: [mathematicskit](https://github.com/cpoli/mathematicskit),
+[physicskit](https://github.com/cpoli/physicskit) and
+[chemistrykit](https://github.com/cpoli/chemistrykit).
+
+MIT license; see [LICENSE](LICENSE). To cite blockchainkit, see
+[CITATION.cff](CITATION.cff).