add new track_peers stage

[rkuhn]

This stage will replace pull+receive_header+validate_header stages as well as incorporate the upstream peer tracking currently performed in the HeadersTree that is employed by select_chain. This is a sketch of the envisioned consensus stages, whereof this PR is the first step.

This is also the first step of #658.

Summary by CodeRabbit

• New Features

  • Added peer tracking functionality for chain synchronization operations with comprehensive error handling
  • Enhanced block header validation with detailed error classification

• Improvements

  • Strengthened era type system with improved naming conventions
  • Refined error reporting for invalid header heights, points, and variants
  • Improved network stage logging for better observability

• Refactor

  • Reorganized module structure for better maintainability

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

Walkthrough

This PR consolidates the amaru-slot-arithmetic crate into amaru-kernel by moving all type definitions (Slot, Epoch, TimeMs, EraName, EraParams, EraHistory) and implementations directly into amaru-kernel. It relocates chain store effects from amaru-consensus to amaru-protocols, introduces a new track_peers stage for peer state management, and updates type representations to use strongly-typed enums (EraName) instead of numeric identifiers across the consensus pipeline.

Changes

Cohort / File(s)	Summary
Crate Removal crates/amaru-slot-arithmetic/*	Entirely removes the amaru-slot-arithmetic crate (Cargo.toml, lib.rs, and module declarations). All 1294 lines of slot/epoch/era-history logic are deleted; types are now in amaru-kernel.
Kernel Type Consolidation crates/amaru-kernel/src/cardano/{slot,epoch,era_name,era_params,time_ms}.rs, crates/amaru-kernel/src/cardano.rs	Introduces four new public modules (slot, epoch, era_name, era_params, time_ms) in amaru-kernel, hosting Slot, Epoch, EraName, TimeMs, and EraParams types with full CBOR serde, arithmetic, and conversions (1613 lines added).
Era History Expansion crates/amaru-kernel/src/cardano/era_history.rs, crates/amaru-kernel/src/cardano/block.rs	Significantly expands EraHistory API with Bound, Summary, EpochBounds, and EraHistoryError structures (993 lines); adds public methods for slot/epoch/time conversions; updates Block era field from u16 to EraName.
Consensus Store Relocation crates/amaru-consensus/src/effects/store_effects.rs, crates/amaru-protocols/src/store_effects.rs	Removes 534-line Store impl from amaru-consensus effects; relocates Store, StoreHeaderEffect, and related effect types to amaru-protocols, exposing them publicly with new constructors.
Consensus Effects Refactoring crates/amaru-consensus/src/effects/{base_effects,consensus_effects,metrics_effects,mod}.rs	Replaces derive(Clone) with manual Clone impls on Base, ConsensusEffects, and Metrics; relaxes generic bounds (removes Clone requirement); adds inherent accessors (store, mempool, network, ledger, base, metrics) on ConsensusEffects; updates public re-exports.
New Track Peers Stage crates/amaru-consensus/src/stages/track_peers.rs, crates/amaru-consensus/src/stages/mod.rs	Adds 1287-line track_peers module implementing peer state management (TrackPeers struct, PerPeer, TrackPeersMsg enum); includes validate_header, roll_forward, roll_backward methods; extensive test coverage.
Error Type Expansion crates/amaru-consensus/src/errors.rs	Adds three new ConsensusError variants: InvalidHeaderHeight, InvalidHeaderPoint, InvalidHeaderVariant; updates error message text for InvalidHeaderParentData.
ChainSync Message & Type Updates crates/amaru-protocols/src/chainsync/{messages,initiator,responder,mod}.rs	Changes HeaderContent.variant from u8 to EraName; adds HeaderContent::new and with_bytes constructors; updates ChainSyncInitiatorMsg to add handler and msg fields; makes InitiatorResult Clone-able.
EraName & Era Tag Refactoring crates/amaru-kernel/src/cardano/network_block.rs, crates/amaru-protocols/src/blockfetch/{initiator,responder}.rs	Changes NetworkBlock.era_tag from u16 to EraName; updates encoding/decoding to use EraName; modifies test assertions to use EraName::Conway instead of numeric 7.
Cross-Crate Import Migration crates/amaru-protocols/src/{blockfetch/mod,connection,manager,keepalive/tests,tests/test_cases,tx_submission/tests}, crates/amaru-kernel/src/lib.rs	Updates all import paths: EraHistory, Epoch, Slot, TimeMs, EraName now sourced from amaru-kernel instead of amaru-slot-arithmetic; updates Manager and Connection type signatures.
Workspace & Manifest Updates Cargo.toml, crates/amaru-kernel/Cargo.toml, crates/amaru-consensus/Cargo.toml, crates/amaru-ledger/Cargo.toml, crates/amaru-protocols/Cargo.toml, crates/amaru/Cargo.toml	Removes amaru-slot-arithmetic workspace member from all manifests; adds num and cbor4ii deps to amaru-kernel; updates dev-dependencies in amaru-consensus.
Ledger & CLI Updates crates/amaru-ledger/src/governance/ratification.rs, crates/amaru/src/bin/amaru/cmd/convert_ledger_state.rs, crates/amaru/src/bootstrap.rs, crates/amaru/src/stages/{build_stage_graph,mod}.rs, crates/amaru/tests/summary.rs	Updates ledger tests and CLI to use TimeMs/EraName; changes PAST_ERAS_NUMBER from i32 to u8; moves ResourceHeaderStore/ResourceParameters imports from amaru-consensus to amaru-protocols; adds InvalidHeaderHeight/Point/Variant error handling.
Pure-Stage Utilities crates/pure-stage/src/{stage_ref,trace_buffer,simulation/running/mod}.rs	Adds AsRef<str> impl to StageRef; adds iter_entries() method to TraceBuffer; adds trace_buffer() accessor to SimulationRunning; simplifies StageRef Debug formatting.
Simulation & Docker simulation/amaru-sim/src/simulator/run.rs, docker/Dockerfile.amaru, .github/workflows/continuous-integration.yml	Updates import paths in simulator; removes amaru-slot-arithmetic from riscv32 CI target; removes Dockerfile COPY for amaru-slot-arithmetic.

Sequence Diagram

sequenceDiagram
    participant Peer as Peer (Upstream)
    participant TP as TrackPeers Stage
    participant CO as ConsensusOps
    participant DL as Ledger/Store
    participant Mgr as Manager (Downstream)

    Peer->>TP: ChainSyncInitiatorMsg (FromUpstream)
    TP->>TP: Match message variant
    
    alt Initialize
        TP->>TP: Add peer to upstream map
        TP->>Mgr: Signal peer ready
    else IntersectFound
        TP->>TP: Update peer current tip
    else RollForward
        TP->>CO: validate_header(peer, raw_header)
        CO->>DL: Decode & validate BlockHeader
        DL-->>CO: BlockHeader result
        CO-->>TP: Validated header
        TP->>CO: roll_forward(peer, header, tip)
        CO->>DL: Store header, update chain state
        DL-->>CO: Result<Tip>
        CO-->>TP: Updated tip
        TP->>TP: Update peer highest
        TP->>Mgr: Send downstream Tip event
    else RollBackward
        TP->>CO: roll_backward(peer, current, tip)
        CO->>DL: Rollback chain state
        DL-->>CO: Result<()>
        CO-->>TP: Rollback result
        TP->>TP: Update peer current
    end
    
    TP-->>Peer: State update (continue/stop)

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~135 minutes

Reasoning: This PR is substantial and heterogeneous. The scope spans 40+ files across consensus, protocols, kernel, and application layers. Key complexity drivers: (1) large-scale crate consolidation with 1294 lines removed + 1613 lines of new type definitions; (2) cross-cutting import refactors affecting module visibility and type paths throughout the codebase; (3) new stage implementation with 1287 lines of logic and extensive test coverage; (4) public API surface changes (Clone trait implementations, accessor methods, type signature changes in several key structs); (5) error handling enhancements requiring review across multiple call sites; (6) interconnected refactors in consensus effects, store relocation, and chain-sync message types that demand careful reasoning about each integration point.

Possibly related issues

• move upstream peer tracking and block validation out of select_chain stage #658: Introduces the new track_peers stage for peer tracking during chain synchronization, directly addressing the goal to factor out upstream peer tracking from select_chain into a dedicated stage.

Possibly related PRs

• feat: more encapsulated effects #488: Introduces ConsensusOps/BaseOps/MetricsOps traits, moves store operations to external effects, and adds ConsensusEffects accessors—directly overlaps with the consensus effects refactoring in this PR.
• fix: log again tip changes #531: Modifies peer-tracking and chain-sync pipeline (track_peers/receive_header/pull stages and related message handling), parallel to the track_peers stage introduction here.
• feat: make ledger wasm/riscv compatible #108: Performs the same cross-crate refactor: removes amaru-slot-arithmetic and consolidates types (EraName, Slot, Epoch) into amaru-kernel with updated imports throughout.

---

Like a proper code reno, mate—we've gutted the dodgy extension (goodbye amaru-slot-arithmetic!) and given amaru-kernel a fresh coat of paint with Slot, Epoch, and EraName living in their new digs. 🏠 Out with the u16 era tags, in with strongly-typed EraName variants (no more "what's 7 again?" moments). Plus, we've spun up a shiny new track_peers stage that's basically the bouncer checkin' peer state like a nightclub list—validatin' headers and keepin' the blockchain in sync. Not gonna lie, it's a pretty epic restructure. 🎬✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 77.72% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'add new track_peers stage' accurately captures the primary change—introducing a new consensus stage module for peer tracking.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch rk/track-peers

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}