blinklabs-io / blinklabs-io/dingo
test(ledger): publish an evidence-backed validation coverage matrix
- Dominant language
- Go
- Stars
- 48
- Forks
- 13
- Avg merge
- 1d 10h
- Merged PRs (30d)
- 603
Description
## Problem
The README feature matrix still marks broad Ledger and Phase-1 validation areas incomplete, while the implementation contains Conway ledger rules, header validation, and conformance vectors. There is no authoritative mapping from Cardano validation requirements to implementation and test evidence.
This makes both directions unsafe: implemented behavior can appear missing, and a broad completed checkbox can imply coverage that has not been demonstrated. Block-producer and relay readiness cannot be assessed from the current matrix.
## Scope
Create one evidence-backed validation coverage source for every supported era and validation layer, including:
- Header envelope, previous-hash/block-number ordering, body size/hash, operational certificate, KES, VRF, and leader eligibility.
- Transaction body and witness/phase-1 rules.
- UTxO accounting, fees, validity intervals, collateral, reference inputs, scripts/datums/redeemers, and value preservation.
- Certificates, delegation, pools, rewards, governance, protocol-parameter updates, and epoch-boundary transitions.
- Roll-forward, rollback, hard-fork boundary, and bootstrap/trust-boundary behavior.
For each requirement record:
- Supported era and rule/spec identifier.
- Implementation location.
- Status: implemented, partial, intentionally unsupported, or missing.
- Unit/conformance/end-to-end test evidence and fixture origin.
- Any fail-closed behavior when the rule cannot be evaluated.
Use a machine-readable or otherwise single-source format that can render the public feature matrix without maintaining a second hand-edited status list.
## Acceptance criteria
- [ ] Every inbound block/header/transaction validation path is represented for each supported era.
- [ ] Every completed entry links to executable test evidence, not only an implementation file.
- [ ] Partial and missing entries state the exact predicate or transition still absent.
- [ ] Conformance-vector provenance and backend coverage are recorded.
- [ ] Historical replay, trusted bootstrap, live sync, mempool admission, and local forging are distinguished where they execute different validation paths.
- [ ] Unsupported or unevaluable consensus rules fail closed unless the documented bootstrap trust boundary and explicit validation settings permit the skip.
- [ ] CI detects stale implementation/test references and prevents undocumented completed entries.
- [ ] The README feature section is generated from or replaced by the authoritative matrix.
- [ ] `ARCHITECTURE.md` explains where header, ledger, mempool, and forging validation responsibilities live.
- [ ] Mainnet-ready documentation cannot claim complete validation while any required rule remains partial or missing.
## Concrete coverage gap (2026-08-21 audit)
`TestRulesConformanceVectorsWithResults` reports 315/315 vectors passing, but that result does not exercise Dingo’s production validation boundary:
- `ouroboros-mock/conformance.Harness.decodeTransaction` always decodes `conway.ConwayTransaction`, so this is not every supported era;
- the harness calls `common.VerifyTransaction` directly with `ConformanceValidationRules`, bypassing `ledger/eras.ValidateTxByron` through `ValidateTxDijkstra` and the distinct live replay, mempool, forging, and block-pipeline entry paths;
- `ConformanceValidationRules` explicitly excludes fee-too-small and max-transaction-size validation; and
- the direct upstream Plutus rule bypasses Dingo’s local Conway Plutus context, required-redeemer, fee, and slippage logic.
This explains how production-path defects can coexist with a 100% conformance result. The matrix and CI gate must distinguish upstream-rule coverage from Dingo-wrapper and end-to-end coverage, and must list every deliberately excluded predicate. A green aggregate must not imply that excluded rules, non-Conway eras, or production entry paths were validated.
## Production validity-tag gap (2026-08-21 audit)
Inbound block apply calls no era validator at all when `tx.IsValid()==false`, despite the era validators documenting that Phase-1 rules and required redeemers still apply. Those validators also skip Phase-2 for an invalid tag, so Dingo never verifies that the script actually fails. For `isValid=true`, pre-Dijkstra Plutus failure is logged and then erased with “trusting isValid=true”.
The Alonzo UTXOS rule evaluates both branches: a valid tag with failing scripts is rejected, and an invalid tag with passing scripts is rejected. The production block path therefore accepts both classes of local disagreement. Add explicit Alonzo/Babbage/Conway vectors at replay, mempool, forging, and inbound-block boundaries; no path may trust the tag instead of reproducing the UTXOS result.
### Historical replay boundary
The default `ValidateHistorical=true` still disables local Phase 2 for blocks at or before tip minus `k`, while `ARCHITECTURE.md` describes complete from-origin replay. The coverage matrix must distinguish trusted previously validated input from arbitrary historical replay and must not mark Phase 2 covered where `skipPhase2Validation` is active.
Contributor guide
Research direction
Start with ouroboros-mock/conformance.Harness.decodeTransaction, common.VerifyTransaction, the ledger/eras.ValidateTxByron through ValidateTxDijkstra path, and ARCHITECTURE.md/README feature coverage. Run the conformance tests and trace replay, mempool, forging, and inbound-block entry points to compare upstream and Dingo-specific validation. Done means one authoritative matrix records every supported era, predicate, execution path, test provenance, and deliberate gap, with CI detecting stale or undocumented claims.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- blockchain, go
- Domain
- blockchain, ci-cd, documentation, testing-qa
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100