ADR 0010: Leios (Musashi) serialization & BlockChainDataListener integration design #170

Summary

With the transport-only Leios mini-protocols (leios-notify = 18, leios-fetch = 19) landed for the Musashi prototype testnet (#167, ADR 0007), the next layer is serialization for the Leios data structures and integration into the existing sync surface.

ADR 0010 designs that layer with four goals:

1. Apps using BlockSync / BlockRangeSync (e.g. yaci-store) keep receiving ranking blocks through BlockChainDataListener.onBlock(era, block, txs) with zero listener API change — on mainnet and on Musashi.
2. New default listener methods (onEndorserBlock, onLeiosVotes) surface Endorser Blocks and votes to apps that opt in, on the same listener and the same connection.
3. The same application code works against mainnet (Leios inactive) and Musashi (Leios active), selected by network magic + handshake — not by code changes.
4. yaci-store's mandatory change reduces to mapping the new Era.Dijkstra constant.

Design (three additive layers)

• Layer 1 — Dijkstra era & ranking-block continuity (core): Era.Dijkstra(8) + EraUtil mapping; shape-guarded parsing of the RB header's trailing [eb_hash, eb_size] announcement extension; nullable raw leios_cert / peras_cert body fields; a robust pre-/post-Babbage header routing heuristic.
• Layer 2 — Leios domain models & serializers (core): model/leios/* (EndorserBlock, LeiosVote, EndorserBlockTx, …) with shape-tolerant deserializers (both EB dialects, 3/4-element votes, ns8 tx-era mapping) that decode the opaque LeiosRawCbor payloads above the transport layer, always retaining raw CBOR.
• Layer 3 — Listener & sync integration (helper): event-carrier callbacks on BlockChainDataListener, an internal LeiosSyncCoordinator (offer-gated fetch, per-point state machine), and opt-in LeiosConfig wiring (AUTO | ENABLED | DISABLED) that attaches the Leios agents to the same TCPNodeClient connection.

Everything is pinned to what the live Musashi network speaks today (cardano-blueprint leios-prototype @ 188183b), with a future-proofing map for known drift (blueprint head vote/body changes, CIP-0164 final shapes).

Plan

• PR-A: core era continuity + fixtures captured from the live network
• PR-B: Leios models & serializers + golden tests
• PR-C: helper listener/coordinator integration + default-disabled Musashi integration test
• yaci-store validation run against a local Musashi relay

ADR: adr/0010-leios-musashi-serialization-and-listener-integration.md (PR to follow).