refactor(internal): improve clarity and maintainability of alonzoTxOutParser

[newhoggy]

Changelog

- description: |
    Refactored the alonzoTxOutParser function to improve code clarity and maintainability
    through better variable naming, consolidated TxOut construction, and enhanced documentation
  type:
    - refactoring    # QoL changes
  projects:
    - cardano-api

Context

This PR refactors the alonzoTxOutParser function in the Cardano API's transaction output module to improve code readability and maintainability. The parser is responsible for deserializing Alonzo-era transaction outputs from JSON, handling various datum configurations (no datum, datum hash only, or supplemental datum with both hash and JSON value).

The refactoring addresses code duplication and unclear variable naming that made the parsing logic harder to understand and maintain. No functional changes were made - this is purely a code quality improvement.

Progress for #926

How to trust this PR

This refactoring maintains identical functionality while improving code organization:

1. No behavioral changes: The parser produces the same TxOut structures for all input cases
2. Preserved error handling: All error conditions and messages remain unchanged
3. Maintained type safety: No changes to type signatures or constraints

To verify the refactoring:

• All existing tests continue to pass without modification
• The parser handles all four datum scenarios exactly as before:
  • No datum (Nothing, Nothing)
  • Datum hash only (Nothing, Just hash)
  • Supplemental datum (Just json, Just hash)
  • Invalid state (Just json, Nothing)

Key improvements made:

• Reduced code duplication: Extracted address and value parsing to occur once instead of in each branch
• Single TxOut construction: Consolidated TxOut creation to a single point, improving maintainability
• Clearer variable names: Renamed mDatumVal to mDatumJson and dVal to datumJson to clarify they contain JSON representations
• Better code organization: Separated datum parsing logic from reference script handling
• Enhanced documentation: Added descriptive comments explaining each datum parsing case

Checklist

• Commit sequence broadly makes sense and commits have useful messages
• New tests are added if needed and existing tests are updated. See Running tests for more details
• Self-reviewed the diff

[Jimbo4350]

Good first step 👍 . Have you checked if any tests have failed in cardano-cli?

[newhoggy]

Good first step 👍 . Have you checked if any tests have failed in cardano-cli?

Good call. I'll run the tests.