feat(transaction-fee-charge-audit): explain offered vs charged transaction fees

[chainsmt]

Closes #468

Summary

Adds Transaction Fee Charge Audit under features/transaction-fee-charge-audit/. For one settled Horizon transaction it explains the maximum fee offered versus the fee actually charged, distinguishes classic vs fee-bump envelopes, and attaches ledger/network context — without predicting future inclusion prices.

Motivation

Operators often see max_fee and fee_charged in Horizon JSON but still misread fee-bump wrappers (outer bid vs inner bid) or silently accept missing fee fields. This tool normalizes those fields, computes an exact stroop difference, and fails loudly when the audit would be incomplete.

What this PR does

• Validates a 64-character transaction hash locally before networking.
• Fetches GET /transactions/{hash} on the selected network and identifies classic vs fee-bump from envelope_xdr (fallback: fee_account) via lib/fee-fields.ts.
• Normalizes max_fee and fee_charged as stroop strings and computes the exact difference with BigInt (lib/stroop-difference.ts) — no floats.
• Shows operation count, selected network, and referenced ledger context (lib/ledger-context.ts → GET /ledgers/{sequence} for closed time / base fee labels).
• For fee-bump envelopes: outer fee source and outer bid drive the offered/charged comparison; the inner fee bid is displayed separately and is not treated as what paid once wrapped.
• Absent or malformed fee fields return invalid_fee_data — an explicit incomplete audit with actionable copy, not a guessed difference.
• Full feature contract: schema, copy, hook, FeeBreakdown / EnvelopeType / LedgerContext UI, MSW, classic + fee-bump fixtures, unit/a11y/e2e (including fee-bump journey).

Architecture notes

• Slice-only: features/transaction-fee-charge-audit/.
• Historical charged fee is evidence only — UI/copy never frames it as a fee-market forecast.
• Never accepts, displays, stores, or transmits secret keys.

Acceptance criteria coverage

• Validate hash; identify classic vs fee-bump
• Show maximum fee, charged fee, exact difference in stroops
• Display operation count, referenced ledger, selected network
• Identify fee-bump outer fee source; keep inner fee fields separate
• Handle absent/malformed fee fields as incomplete audit

Out of scope

• Fee bidding / submission
• Future inclusion price prediction
• Changes outside this feature directory

Test plan

• npm run verify:features -- transaction-fee-charge-audit
• npm test -- features/transaction-fee-charge-audit (51 tests)
• Manual: classic settled tx → offered/charged/diff + ledger
• Manual: fee-bump settled tx → outer source + inner bid separate
• Manual: malformed fee fields fixture → invalid_fee_data copy

[drips-wave]

@chainsmt Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits