Skip to content

v0.6.0

Choose a tag to compare

@github-actions github-actions released this 06 Sep 17:47
· 57 commits to main since this release

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.rs beside 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_exchanges makes
    produce_block keep a copy of each Engine API call in Produced::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 cupel for 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 by docs/make-diagrams.py and 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
    node label rather than by a separate dashboard.

    The panel that earns it is Transactions geth refused. A transaction paying
    under --miner.gasprice is 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_underpriced is where that says so, and now it is on a screen.

  • Metrics in lab mode. compose/lab.yml had no --metrics flags at all, so
    the default one-command mode exposed nothing and the cupel-execution scrape
    job existed only for the devnet. geth now serves metrics on 6060 there,
    scraped as a fourth target in the same job, labelled lab. Port 6060 rather
    than 6061 because the first devnet node holds 6061, 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.sh pulls every
    expr out 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, so chain_execution, chain_validation, chain_write and
    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_isReplacedNotAdjusted rather than test_approveRace_…,
    test_shares_anInflatedPriceRoundsTheNextDepositDown rather 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.