Repository navigation
v0.6.0
Five phases built the apparatus. This is the first release aimed at somebody
using it rather than at the thing working.
Added
-
Guided walkthroughs —
cupel lab. Numbered lessons that do real work
against a running chain and narrate it: the four Engine API calls that make a
block, printed request and response; the three states a transaction passes
through and which question distinguishes them; slots, epochs and what has to
happen twice before a block is final; and the same question asked of three
clients at once. Nothing is simulated and nothing is pre-recorded — with no
chain up, a walkthrough fails, which is the honest outcome.The prose lives in
crates/cupel/src/lab.rsbeside the code that produces the
output, because a lesson kept in a separate document drifts from the thing it
describes and there is no way to notice. -
The producer can narrate itself.
Config::record_exchangesmakes
produce_blockkeep a copy of each Engine API call inProduced::exchanges,
so walkthrough 1 shows the real sequence rather than a reimplementation of it
standing next to a lesson about it. Off by default: producing a block is the
hot path and a payload can be large, so the copies are made only when
something intends to read them. -
Release binaries. A tag builds
cupelfor Linux, macOS on both
architectures, and Windows, smoke-tests each one, and attaches them to the
release with checksums and notes lifted from this file. Docker is needed
either way, but asking somebody to install Rust before they can look at a
block is a tax with nothing behind it. -
The architecture diagrams live in the repository, one file per theme so
GitHub picks the right one, generated bydocs/make-diagrams.pyand checked
in CI against it — a diagram edited by hand and not regenerated is a picture
of a system that no longer exists. -
A third dashboard, Cupel — execution. Prometheus had been scraping geth
since phase C and almost nothing read the result: two metrics out of the 899
the node exposes. This is the node's own view — head with the safe and
finalised markers trailing it, the transaction pool, Engine API latency and
call rate, JSON-RPC, peers, state cache, disk — in both modes, told apart by a
nodelabel rather than by a separate dashboard.The panel that earns it is Transactions geth refused. A transaction paying
under--miner.gaspriceis accepted into the pool, returns a hash, and is then
skipped by the payload builder for ever; nothing errors and nothing logs, so
the only symptom is a transaction pending while empty blocks keep coming.
txpool_underpricedis where that says so, and now it is on a screen. -
Metrics in lab mode.
compose/lab.ymlhad no--metricsflags at all, so
the default one-command mode exposed nothing and thecupel-executionscrape
job existed only for the devnet. geth now serves metrics on6060there,
scraped as a fourth target in the same job, labelledlab. Port6060rather
than6061because the first devnet node holds6061, and the README promises
both modes can run at once — a clash would have surfaced as a Docker bind
error saying nothing about Cupel. -
CI checks every dashboard panel against a live Prometheus.
check-dashboards.shpulls every
exprout of every dashboard, asks a real Prometheus scraping a real chain,
and fails on any that returns no series. Both the lab and network jobs run it,
in their own mode, with an explicit skip-list for panels whose emptiness is a
property of the mode rather than a fault.This exists because a dashboard cannot fail loudly. Rename a metric upstream
and the panel does not error — it draws an empty box, which on a lab chain
looks exactly like a quiet one. Both well-known community geth dashboards died
this way and still render: the EF devops fork is InfluxDB-only and last revised
in 2021, sochain_execution,chain_validation,chain_writeand
trie_memcache_*are all gone from geth 1.17; the other needs a JSON-RPC
exporter last touched in 2019, before the merge. Neither was imported, and this
check is what stops the same rot starting here.
Changed
- Reframed around the machinery rather than its failure modes. The project
is for showing how Ethereum works — the Engine API handshake that produces a
block, three clients arriving at the same finalised chain, a network forming
from a single bootnode — and the writing now leads with that. The Solidity
tests are unchanged in what they run and renamed for what they demonstrate:
test_allowance_isReplacedNotAdjustedrather thantest_approveRace_…,
test_shares_anInflatedPriceRoundsTheNextDepositDownrather than
test_inflationAttack_…. An allowance being a standing permission and a share
price being a ratio with a remainder are facts about the standards; they read
better as such.
Phase F: a Chainlink oracle.