ade_core
BLUE- 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 soleDC-CONS-03selector); the BLUE candidate/header-validation authorities the live SELECT path reuses; thePraosChainDepState/Nonceevolution (incl.overlay_recovered_eta0and the rolling live-follow nonce transitionDC-EPOCH-16); the HFC era-scheduleEraSchedule(locate— the deterministic slot→epoch authority every boundary decision uses) + the freeze-window helperpraos_rsw_slots(=ceil(4k/f), the single RSW derivation shared by the genesis parser,rsw_for_cli, and the S2sidecar_freeze_rsw); the closedLeaderCheckVerdict; theSecurityParam(k = 2160);consensus::ledger_view::LedgerView. +1 type sincecdcd9397—LeaderEligibility(the new closed leader-eligibility classification). Otherwise byte-stable across the span; the native next-epoch derivation lives inade_ledger/ade_runtime/ade_node, consumed THROUGH the existingledger_viewauthority, 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_headervalidates oneHeaderInput→ValidatedHeaderSummary.consensus::praos_stateevolves 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::locatemaps aSlotNoto 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_chainis the soleDC-CONS-03fork-choice authority; arrival-order-independent (CN-CONS-01).validate_and_apply_headeris the sole candidate-summary source — a RED-mintedValidatedHeaderSummaryMUST NOT reachselect_best_chain(DC-NODE-35). (3) Construct semantic types from raw bytes. (4) Depend on any RED/GREEN crate (onlyade_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 singlepraos_rsw_slots—ade_coreMUST NOT accept a freeze boundary from a wall-clock or a second RSW formula, and the freeze rule staysNone ⇒ CANDIDATE_FREEZE_INERT. (8, MEM cross-refDC-MEM-05/06) the consensus authority MUST stay independent of the process allocator + any UTxO storage-backend iteration order. (9, ECA cross-refDC-EPOCH-03/12/14,DC-EVIEW-11)ade_coreMUST NOT gain a SECOND leader schedule or nonce authority for the next epoch — the promoted view is consumed THROUGH the existingledger_view/ leader-check authorities, never by a parallel selector insideade_core; the SAMEEraSchedule::locateanswers 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 + thesidecar_freeze_rswRSW 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
| Script | Enforces |
|---|---|
| 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 |
|
| 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 |
|
| ci_check_producer_praos_vrf.sh | CN-FORGE-04 |
| ci_check_warmstart_eta0_overlay.sh | ECA-B (band 7) |
Related invariants — 36
| ID | Status | Statement |
|---|---|---|
| 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) |