Cardano Updates

fix(era-independent): correct max length in readStringOfMaxLength error message

Completes the integration of caseBabbageOnlyOrConwayEraOnwards by adding it
to the public API exports, ensuring it's available alongside other era case
functions like caseByronOrShelleyBasedEra.

- Add caseBabbageOnlyOrConwayEraOnwards to Cardano.Api.Era export list
- Create new "Case on BabbageEraOnwards" subsection for organization
- Add corresponding export section in Internal.Case module
- Implement the function to handle Babbage-only vs Conway+ era branching

The function enables cleaner conditional logic when dealing with features
that differ between Babbage and Conway eras, particularly useful for
handling Conway-specific governance features and protocol parameters.

Implements extensive test coverage for the ToJSON and FromJSON instances
of TxOut across all eras and contexts, ensuring robust JSON serialization
and deserialization behavior.

Test modules added:
- Test.Cardano.Api.TxOut.Gen: Specialized generators for TxOut with specific
  datum types (no datum, datum hash, supplemental, inline) and invalid JSON
  scenarios for error testing
- Test.Cardano.Api.TxOut.Helpers: Test utilities including JSON field
  assertions, parse failure validators, and datum equality checks
- Test.Cardano.Api.TxOut.Json: Main test module organizing all test suites
- Test.Cardano.Api.TxOut.JsonRoundtrip: Roundtrip property tests for all
  eras (Shelley through Conway) in both CtxTx and CtxUTxO contexts
- Test.Cardano.Api.TxOut.JsonEdgeCases: Edge case tests for supplemental
  datum behavior, null field handling, and ToJSON output validation
- Test.Cardano.Api.TxOut.JsonErrorCases: Error case tests for conflicting
  datums, mismatched hashes, partial fields, and invalid data

Coverage highlights:
- All eras from Byron through Dijkstra (where supported)
- Both transaction contexts (CtxTx and CtxUTxO)
- All datum types including edge cases like supplemental datums
- Comprehensive error handling validation
- JSON field presence and null handling verification

This test suite ensures the TxOut JSON instances maintain backward
compatibility while properly handling the complex datum type variations
across different Cardano eras.

Refactors the alonzoTxOutParser function to enhance code readability and
maintainability by introducing clearer variable names and improving the
logical flow of datum field parsing.

Key improvements:
- Rename ambiguous variables (mDatumVal -> mDatumJson, dVal -> datumJson)
  to clearly indicate they contain JSON representations of datum values
- Add descriptive comments explaining each datum parsing case:
  * No datum information (Nothing, Nothing)
  * Datum hash only (Nothing, Just hash)
  * Both hash and JSON for supplemental datum (Just json, Just hash)
  * Invalid state with JSON but no hash (Just json, Nothing)
- Extract datum parsing into a dedicated section, separating it from
  reference script handling for better code organization
- Use more descriptive variable names (parsedAddress, parsedValue) to
  distinguish parsed results from raw JSON fields

Refactor the case expression to return a tuple of (TxOutDatum, ReferenceScript)
instead of constructing TxOut in each branch.

Signed-off-by: jeluard <[email protected]>

Signed-off-by: jeluard <[email protected]>

Adds inline documentation noting that the CtxUTxO instance still contains
~60 lines of duplicated code in the Babbage/Conway/Dijkstra cases that
could potentially be refactored using a similar approach to the CtxTx
instance refactoring.

The comment includes:
- NOTE: Identifies the specific lines containing duplication
- POTENTIAL REFACTORING: Suggests how it could be addressed (similar to
  parseInlineDatum helper in CtxTx)
- BLOCKER: Documents the key difference that must be preserved - CtxUTxO's
  alonzoTxOutParser doesn't handle supplemental datums, unlike CtxTx

This serves as documentation for future maintainers who may want to
complete the refactoring, while explaining why it wasn't done in this PR.

Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

This commit adds detailed inline documentation to explain the design decisions,
assumptions, and potential issues in the refactored TxOut JSON parsing code.

Key documentation areas:

1. parseBabbageOnwardsTxOut:
   - MOTIVATION: Explains this eliminates ~100 lines of duplication
   - DESIGN: Documents the two-phase parsing strategy (Alonzo + Babbage reconciliation)
   - ASSUMPTION: Notes BabbageEraOnwards covers exactly three eras

2. parseInlineDatum:
   - CRITICAL DISTINCTION: Explains why Babbage uses scriptDataJsonToHashable
     vs Conway+ using scriptDataFromJson (CBOR encoding preservation requirement)
   - VALIDATION: Documents hash verification logic
   - POTENTIAL ISSUE: Warns about wildcard pattern assumption

3. reconcileDatums:
   - BACKWARDS COMPATIBILITY: Lists the three valid JSON formats accepted
   - ERROR HANDLING: Explains conflicting datum detection and error messages
   - EXHAUSTIVENESS: Documents how direct GADT matching enables compiler verification
     when new eras are added to BabbageEraOnwards

4. eraName helper:
   - Documents switch from ShelleyBasedEra to direct BabbageEraOnwards matching
   - Explains benefit: compiler enforces exhaustiveness, preventing incomplete updates

Creates parseBabbageOnwardsTxOut helper function to eliminate the final
source of duplication in the FromJSON instance. The three era cases
(Babbage, Conway, Dijkstra) now each call this single helper function.

This completes the refactoring by:
- Reducing the FromJSON instance by ~10 more lines
- Making the code structure clearer with simple era-based dispatch
- Consolidating all Babbage+ era parsing logic in one place
- Maintaining full backwards compatibility with all tests passing

The main case expression now clearly shows the parsing strategy for
each era, with complex logic extracted into well-named helper functions.

Replaces two nearly-identical datum reconciliation functions with a
single reconcileDatums function that works for all Babbage+ eras,
eliminating ~40 lines of duplicated code.

The unified function:
- Works with BabbageEraOnwards constraint (covering Babbage, Conway, Dijkstra)
- Uses era witness to construct appropriate ReferenceScript types
- Generates era-specific error messages dynamically
- Handles conflicting Alonzo-style and Babbage-style datums

All tests pass, confirming behavioral equivalence and backwards
compatibility.

Eliminates ~50 lines of code duplication by extracting the repeated
inline datum parsing logic from Babbage/Conway/Dijkstra cases into a
single parseInlineDatum helper function.

The refactored helper:
- Parses both inlineDatumhash and inlineDatum fields
- Validates that the datum matches its hash
- Handles era-specific parsing differences between Babbage
  (scriptDataJsonToHashable) and Conway/Dijkstra (scriptDataFromJson)
- Maintains identical behavior with all existing tests passing

This consolidation improves maintainability by ensuring consistent
error handling and validation across all Babbage+ eras.

Creates parseBabbageOnwardsTxOut helper function to eliminate the final
source of duplication in the FromJSON instance. The three era cases
(Babbage, Conway, Dijkstra) now each call this single helper function.

This completes the refactoring by:
- Reducing the FromJSON instance by ~10 more lines
- Making the code structure clearer with simple era-based dispatch
- Consolidating all Babbage+ era parsing logic in one place
- Maintaining full backwards compatibility with all tests passing

The main case expression now clearly shows the parsing strategy for
each era, with complex logic extracted into well-named helper functions.