feat(scenarios): Alpenglow's 150 ms finality case (ideal) + architecture map

[AkashJana18]

What

Two related pieces of work: a new scenario that reproduces the Alpenglow white paper's headline
latency number, and a written architecture map of the project.

1. ideal-fast: Alpenglow finalizes the hero transaction in 150 ms

scenarios/happy-path.json claimed Alpenglow fast-finalizes its hero transaction "~150 ms after the
block lands". It does not — it takes 451 ms, because that transaction lands in the first slice of
its block and waits out the whole 400 ms block assembly before it can even be voted on.

ideal-fast is the same healthy six-region, mainnet-stake, fault-free cluster, with the transaction
submitted at 550 ms so it rides the block's last slice. What is left is pure Votor:

hero tx   submitted 550.0  included 700.0  confirmed 841.4  finalized 849.6   →  149.6 ms
tower     included 700.0  confirmed 887.4  rooted 13115.0                      →  12.4 s
certificates {"fast_finalization": 37, "notarization": 38, "skip": 0}

Grounded in the paper rather than tuned to taste. The white paper (v1.1, §1.3) measures finalization
after a block has been distributed — min(δ80%, 2δ60%) — and Fig. 14 reports a median of roughly
150 ms for randomly chosen leaders. In this run the median validator finalizes the hero block 149.3
ms after receiving it: the same measurement, the same number. Parameters are the paper's, not
invented: Δblock = 400 ms (Table 10), 4-block leader windows, 60%/80% certificate thresholds,
Pareto mainnet-like stake, and the repo's real-world-latency six-region preset.

alpenglow::tests::ideal_fast_matches_the_papers_150ms_median asserts both the transaction timing and
the per-node median, so the seed-pinned numbers cannot silently drift. happy-path's copy is corrected
in the same PR, and the README explains that the 300 ms between the two scenarios is block assembly,
not consensus.

2. docs/architecture.md: the project map

Written for contributors and for reviewers deciding whether the project is credible: system shape,
repository and module tables, scenario → running simulation, one step of the event loop, the
engine/protocol boundary, the trace contract with the four-step recipe for adding an event, the
determinism invariants and why the UI can rewind by replaying, the render pipeline, the
CLI/wasm/scenario/URL surfaces, the test map, "where do I add X", and — deliberately — a closing list
of what is modelled versus simplified (25 vs ~1,500 validators, no Byzantine adversary yet, no
cryptography, constant execution time, abstract network, shortened Δstandstill).

Six Mermaid diagrams, each verified against the Mermaid parser rather than eyeballed. The three
hand-drawn ASCII diagrams in README.md, CLAUDE.md and web/README.md became Mermaid flowcharts
with the same content; existing docs keep their text and link in.

Why reviewers should care

• The UI cannot lie about the protocol. Everything it draws comes from the engine's trace event
  stream; there is no side channel, and no UI-side state that could disagree with the simulation.
• One code path, three consumers. The CLI, the property tests and the browser run the same Rust
  core on the same seed and produce the same trace, so a number in a lesson, in this PR and in a bug
  report are the same number.
• Determinism is verified, not asserted. Every builtin scenario runs twice per protocol and the
  traces are compared byte for byte; that is what lets the browser scrub backwards by rebuilding and
  fast-forwarding instead of shipping snapshots.

Verification

cargo test --workspace (19 unit + 4 property tests, incl. determinism over all six builtin
scenarios) · bun run test (53) · bun run build (strict tsc) · wasm rebuilt ·
Playwright smoke, lesson, share green · every scenario timing in the copy measured with
sim-cli, not written by hand.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
solana-consensus-lab	Ready	Preview	Oct 2, 2026 3:44pm UTC