Modules / ade_core

ade_core

BLUE
BLUE crate
Purpose

The functional core (consensus half): Praos VRF leader-check + the expected-VRF-input recipe; the chain-selection authority consensus::fork_choice::select_best_chain (the sole DC-CONS-03 selector); the BLUE candidate/header-validation authorities the live SELECT path reuses; the PraosChainDepState / Nonce evolution (incl. overlay_recovered_eta0 and the rolling live-follow nonce transition DC-EPOCH-16); the HFC era-schedule EraSchedule (locate — the deterministic slot→epoch authority every boundary decision uses) + the freeze-window helper praos_rsw_slots (= ceil(4k/f), the single RSW derivation shared by the genesis parser, rsw_for_cli, and the S2 sidecar_freeze_rsw); the closed LeaderCheckVerdict; the SecurityParam (k = 2160); consensus::ledger_view::LedgerView. +1 type since cdcd9397 — LeaderEligibility (the new closed leader-eligibility classification). Otherwise byte-stable across the span; the native next-epoch derivation lives in ade_ledger/ade_runtime/ade_node, consumed THROUGH the existing ledger_view authority, never a parallel selector.

Creates

PraosChainDepState, Nonce, EraSchedule, ExpectedVrfInput, LeaderCheckVerdict (closed), LeaderEligibility (closed — NEW), CandidateFragment, TiebreakerView, ValidatedHeaderSummary, HeaderInput, HeaderVrf, Point, BlockDistance, SecurityParam, ActiveSlotsCoeff, LedgerView, candidate/VRF-input/leader-threshold types. 50 public types.

Interprets

Praos header VRF/leader inputs; candidate chain summaries for select_best_chain. validate_and_apply_header validates one HeaderInput → ValidatedHeaderSummary. consensus::praos_state evolves the nonce + overlays the recovered eta0 + drives the rolling live-follow transition (one indivisible transition per validated followed header over {slot, prev_block_hash, vrf_nonce_output, freeze_boundary}; boundary tick → combine + rotation, no reset). EraSchedule::locate maps a SlotNo to its protocol epoch.

MUST NOT

(1) Perform I/O / read a clock / use float / HashMap. (2) Be the home of a SECOND chain selector — select_best_chain is the sole DC-CONS-03 fork-choice authority; arrival-order-independent (CN-CONS-01). validate_and_apply_header is the sole candidate-summary source — a RED-minted ValidatedHeaderSummary MUST NOT reach select_best_chain (DC-NODE-35). (3) Construct semantic types from raw bytes. (4) Depend on any RED/GREEN crate (only ade_types, ade_crypto, minicbor). (5) Add a SECOND expected-VRF-input authority. (6, T-REC-06) PraosChainDepState::overlay_recovered_eta0 — the SINGLE eta0-overlay authority; stays pure. (7, DC-EPOCH-16) the rolling nonce evolution is ONE indivisible BLUE transition; the RSW freeze boundary is derived from era geometry via the single praos_rsw_slots — ade_core MUST NOT accept a freeze boundary from a wall-clock or a second RSW formula, and the freeze rule stays None ⇒ CANDIDATE_FREEZE_INERT. (8, MEM cross-ref DC-MEM-05/06) the consensus authority MUST stay independent of the process allocator + any UTxO storage-backend iteration order. (9, ECA cross-ref DC-EPOCH-03/12/14, DC-EVIEW-11) ade_core MUST NOT gain a SECOND leader schedule or nonce authority for the next epoch — the promoted view is consumed THROUGH the existing ledger_view / leader-check authorities, never by a parallel selector inside ade_core; the SAME EraSchedule::locate answers the boundary for BOTH the activation predicate and the forge epoch-match guard.

Inbound deps

ade_ledger, ade_testkit, ade_core_interop, ade_runtime (window driver + native Mithril assembly + the live-follow nonce tick), ade_node (epoch-activation orchestration + the sidecar_freeze_rsw RSW derivation).

Outbound deps

ade_types, ade_crypto, minicbor. Dev-dep: ade_testkit.

Entry points

ade_core::consensus::{fork_choice::select_best_chain, header_validate::validate_and_apply_header, leader_check::*, praos_state::{PraosChainDepState, Nonce}, candidate::*, header_summary::*, events::{Point, BlockDistance}, ledger_view::LedgerView, vrf_cert::ActiveSlotsCoeff, era_schedule::{EraSchedule, praos_rsw_slots}, praos_leader_value, SecurityParam}.

Key modules

consensus/ (fork_choice.rs, header_validate.rs, candidate.rs, header_summary.rs, events.rs, rollback.rs, leader_check.rs, praos_state.rs, nonce.rs, vrf_cert.rs, ledger_view.rs, era_schedule.rs, encoding.rs).

Depends on

—

Depended on by

—

CI guards — 19

ScriptEnforces
ci_check_chain_selection_arrival_order_independent.sh CN-CONS-01, T-CONS-01
ci_check_consensus_closed_enums.sh CN-CONS-02, DC-CONS-03, DC-CONS-04, DC-CONS-05, DC-CONS-06, DC-CONS-09, DC-CONS-10, DC-CONSENSUS-01, DC-MEM-01, DC-MEM-02, DC-TXV-01, DC-TXV-02, DC-TXV-03, DC-TXV-04, DC-TXV-05, DC-VAL-01, DC-VAL-02, DC-VAL-03, DC-VAL-04, DC-VAL-05, DC-VAL-06, T-DET-01
ci_check_crypto_vectors.sh DC-CRYPTO-01
ci_check_eview_forecast_crossing.sh

DC-EPOCH-15 (ECA-5)

ci_check_forbidden_patterns.sh DC-LEDGER-08, T-CORE-01, T-CORE-02, T-DET-01
ci_check_forge_purity.sh DC-CONS-13, DC-CONS-14, DC-CONS-15, DC-LEDGER-12
ci_check_forge_slot_authority.sh DC-NODE-45, DC-NODE-46
ci_check_header_body_binding.sh CN-CONS-04
ci_check_hfc_translation.sh DC-EPOCH-02
ci_check_leader_check_authority.sh CN-FORGE-02
ci_check_ledger_determinism.sh DC-LEDGER-01, DC-LEDGER-02, T-DET-01
ci_check_no_chaindb_in_consensus_blue.sh DC-CONS-03, DC-CONS-05, DC-CONS-07, DC-CONSENSUS-01
ci_check_no_density_in_fork_choice.sh CN-CONS-01, CN-CONS-02, CN-CONS-03, CN-CONS-05, DC-CONS-03, DC-CONSENSUS-01, T-CONS-01
ci_check_no_float_in_consensus.sh CN-CONS-05, DC-CONS-03, DC-CONS-08, T-CORE-02
ci_check_node_forge_single_epoch_fail_closed.sh DC-EPOCH-03
ci_check_opcert_closed.sh DC-CONS-11, DC-CONS-12
ci_check_praos_nonce_follow_evolution.sh

DC-EPOCH-16 (ECA-B1/B2)

ci_check_producer_praos_vrf.sh CN-FORGE-04
ci_check_warmstart_eta0_overlay.sh

ECA-B (band 7)

Related invariants — 36

IDStatusStatement
CN-CONS-01 enforced Chain selection must be deterministic for the same candidate chains and protocol observables
CN-CONS-02 declared Supported rollout skew must not allow a single adversarial input to induce persistent honest-node consensus divergence
CN-CONS-03 enforced After temporary partition, honest nodes must converge using only protocol-defined observables and declared emergency procedures
CN-CONS-04 enforced Header validation must bind exactly to the accepted body and consensus context
CN-CONS-05 declared Authoritative consensus decisions must not depend on wall-clock time, arrival-order races, scheduler interleavings, or OS behavior
CN-CRYPTO-02 partial All consensus-relevant hashes must be domain-separated and unambiguous
CN-EPOCH-01 partial Stake, rewards, parameter changes, and governance effects may activate only at protocol-defined epoch boundaries
CN-FORGE-02 enforced Leader-check splits across the RED/BLUE color boundary: RED produces a VRF proof/output for the slot using the operator's VRF signing key; BLUE verifi…
CN-FORGE-04 enforced Producer-side Praos VRF construction must match the Conway/Praos validator authority: the leader VRF proof alpha, the leader-schedule evidence, the Le…
DC-CINPUT-02a enforced PROJECTION EQUIVALENCE. The recovered SeedEpochConsensusInputs projects deterministically to the leadership-consumed PoolDistrView (the full LedgerVie…
DC-CINPUT-03 enforced The producer Praos VRF leader/header input is `praos_vrf_input(slot, eta0)` = `blake2b256(slot_be8 ‖ eta0_32)` (= cardano `mkInputVRF`), where eta0 is…
DC-CONS-03 enforced Praos chain selection ordering: block number first, then Praos TiebreakerView (slot, issuer, op-cert issue number, VRF output). Density-based ordering…
DC-CONS-04 enforced Praos chain-dep state (evolving/candidate/epoch/previous_epoch/lab/last_epoch_block nonces, op-cert counters, last_slot) is owned by N-B consensus, no…
DC-CONS-05 enforced Authoritative rollback must never exceed the security parameter k measured in blocks (mainnet k = 2160). Rollback requests deeper than k return Exceed…
DC-CONS-06 enforced rollback(state, depth) produces state byte-identical to truncated replay from the nearest checkpoint. Rollback that would cross the immutable tip (≥ k…
DC-CONS-07 enforced BLUE consensus must consume the HFC schedule only as a typed EraSchedule value anchored to BootstrapAnchorHash. Genesis text parsing happens in RED; B…
DC-CONS-08 enforced slot_to_time(EraSchedule, SystemStart, SlotNo) is a pure function; no BLUE consensus path may consult the wall clock to derive a slot or UTC instant f…
DC-CONS-09 enforced Consensus-derived queries for slots beyond the ledger-view safe zone return OutsideForecastRange, never guessed values. The bound is derived from era …
DC-CONS-10 enforced A header's op-cert issue counter must be >= the highest observed counter for the same (pool, kes_period). Regression yields HeaderInvalid with a typed…
DC-CONS-11 enforced OpCert kes_period field equals the KES period at the forged slot under an operator-supplied anchor. period_at_slot(slot, anchor) = (slot - anchor) / s…
DC-CONS-12 enforced OpCert serial counter is strictly monotonically increasing per (cold-key, node). BLUE rejects regression or repetition at the RED->BLUE boundary: opce…
DC-CONS-15 enforced Forge is invoked only when leader-check passes. forge_block is a forbidden transition for ticks where is_leader(state, vrf_output, sigma, asc) == fals…
DC-CONSENSUS-01 enforced Chain selection is deterministic and matches Haskell node behavior
DC-CONSENSUS-02 partial Leadership verification is pure
DC-CRYPTO-01 enforced Crypto verification is pure and matches Haskell node on all test vectors
DC-EPOCH-02 enforced Hard fork transitions triggered at deterministic slot/epoch boundaries; era translation functions mandatory; forecast horizon extends to era boundary
DC-EPOCH-03 enforced Single-epoch forge containment on the --mode node spine: in this forge path, a forge is valid only within the single recovered seed epoch. A candidate…
DC-EPOCH-15 enforced Forecast horizon <=> durable N+1 authority promotion. The relay loop's EraSchedule forecast horizon extends past an epoch boundary N->N+1 IF AND ONLY …
DC-EPOCH-16 enforced Rolling Praos chain-dep nonce evolution on the live follow path. Each validated followed header drives ONE indivisible BLUE nonce transition over {slo…
DC-FORGE-01 enforced Given the same canonical input set (slot, eta0, vrf_vk, vrf_proof_or_output, LeaderScheduleAnswer), verify_and_evaluate_leader produces a byte-identic…
DC-NODE-45 enforced ONE bootstrap-bound wall-clock -> absolute-slot authority on the authoritative --mode node producer path. (a) SOLE AUTHORITY: the forge derives its sl…
DC-VAL-01 enforced A block's validity verdict is a pure function of (LedgerState, PraosChainDepState, EraSchedule, LedgerView, block_cbor). No wall-clock, arrival order,…
DC-VAL-06 enforced Every crypto-input, field-size, and structural check on the authority path rejects (produces Invalid) on wrong size or shape and never silently skips.…
T-CONS-01 enforced Chain selection depends only on canonical observables; same candidates -> same tip
T-CORE-02 enforced No wall-clock, unseeded randomness, floats, or nondeterministic collections in authoritative paths
T-DET-01 enforced Same canonical inputs -> same authoritative bytes (per Byte Authority Model)