fix: correct V1/V2 API format type naming and implementation

Root cause: Type names LedgerTransactionExpanded and LedgerTransactionExpandedV1
were inverted from the actual API versions they represented.

- API v1 returns flat format (fields directly on object + metaData)
- API v2 returns wrapped format (tx_json + meta as sibling fields)

But types were named backwards:
- LedgerTransactionExpanded (no V suffix) = claimed v2 but format was flat (v1)
- LedgerTransactionExpandedV1 = claimed v1 but format was wrapped (v2)

Fixed by:
- Renamed LedgerTransactionExpanded -> LedgerTransactionExpandedV2 (now correctly wrapped)
- Renamed LedgerTransactionExpandedV1 -> stays V1 (now correctly flat)
- Added deprecated alias LedgerTransactionExpanded = V2 for backwards compatibility
- Updated Ledger (v2) interface to use V2 type (wrapped)
- Updated LedgerV1 interface to use V1 type (flat)
- Renamed normalizeToV2 -> normalizeToV1 (function actually converts v2 wrapped -> v1 flat)
- Updated hashTxTree to expect v1 flat format (what it actually uses)
- Fixed JSDoc comments to accurately describe format differences

Verified against rippled API-VERSION-2.md which clearly documents:
- API v1: old flat format
- API v2: new wrapped format with tx_json + meta

Author: slurpyone

packages/xrpl/src/models/ledger/Ledger.ts

@@ -57,20 +57,20 @@ interface BaseLedger {
 }
 
 /**
- * Expanded transaction format in API version 2.
+ * Expanded transaction format in API version 1.
  * Transactions are returned as flat objects with the transaction fields
  * directly on the object, plus `hash` and `metaData`.
  */
-export type LedgerTransactionExpanded = Transaction & {
+export type LedgerTransactionExpandedV1 = Transaction & {
   hash: string
   metaData?: TransactionMetadata
 }
 
 /**
- * Expanded transaction format in API version 1.
+ * Expanded transaction format in API version 2.
  * Transactions are wrapped in an object with `tx_json` and `meta` fields.
  */
-export interface LedgerTransactionExpandedV1 {
+export interface LedgerTransactionExpandedV2 {
   tx_json: Transaction
   meta: TransactionMetadata
   hash: string
@@ -80,6 +80,13 @@ export interface LedgerTransactionExpandedV1 {
   ledger_hash: string
 }
 
+/**
+ * @deprecated Use LedgerTransactionExpandedV2 instead. The old name was backwards:
+ * "Expanded" referred to API v2 (wrapped), while "ExpandedV1" was actually the v1 format (flat).
+ * For clarity: LedgerTransactionExpandedV1 = API v1 flat format, LedgerTransactionExpandedV2 = API v2 wrapped format.
+ */
+export type LedgerTransactionExpanded = LedgerTransactionExpandedV2
+
 /**
  * A ledger is a block of transactions and shared state data. It has a unique
  * header that describes its contents using cryptographic hashes.
@@ -93,10 +100,10 @@ export interface Ledger extends BaseLedger {
   ledger_index: number
   /**
    * Transactions applied in this ledger version. When expanded, members are
-   * full representations of the transactions as flat objects with the
-   * transaction fields directly on the object, plus `hash` and `metaData`.
+   * full representations of the transactions wrapped in objects with
+   * `tx_json` and `meta` fields.
    */
-  transactions?: Array<string | LedgerTransactionExpanded>
+  transactions?: Array<string | LedgerTransactionExpandedV2>
 }
 
 /**
@@ -114,8 +121,8 @@ export interface LedgerV1 extends BaseLedger {
   ledger_index: string
   /**
    * Transactions applied in this ledger version. When expanded, members are
-   * full representations of the transactions wrapped in objects with
-   * `tx_json` and `meta` fields.
+   * full representations of the transactions as flat objects with the
+   * transaction fields directly on the object, plus `hash` and `metaData`.
    */
   transactions?: Array<string | LedgerTransactionExpandedV1>
 }

packages/xrpl/src/models/ledger/index.ts

@@ -22,6 +22,7 @@ import {
   LedgerV1,
   LedgerTransactionExpanded,
   LedgerTransactionExpandedV1,
+  LedgerTransactionExpandedV2,
 } from './Ledger'
 import { LedgerEntry, LedgerEntryFilter } from './LedgerEntry'
 import LedgerHashes from './LedgerHashes'
@@ -65,6 +66,7 @@ export {
   LedgerV1,
   LedgerTransactionExpanded,
   LedgerTransactionExpandedV1,
+  LedgerTransactionExpandedV2,
   LedgerEntryFilter,
   LedgerEntry,
   LedgerHashes,

packages/xrpl/src/utils/hashes/hashLedger.ts

@@ -14,6 +14,7 @@ import {
   LedgerVersionMap,
   LedgerTransactionExpanded,
   LedgerTransactionExpandedV1,
+  LedgerTransactionExpandedV2,
 } from '../../models/ledger/Ledger'
 import { Transaction } from '../../models/transactions'
 import { GlobalFlags } from '../../models/transactions/common'
@@ -129,12 +130,13 @@ export function hashLedgerHeader(
 
 /**
  * Compute the root hash of the SHAMap containing all transactions.
+ * Transactions must be in v1 flat format (fields directly on object with metaData field).
  *
- * @param transactions - List of Transactions.
+ * @param transactions - List of v1 flat formatted Transactions.
  * @returns The root hash of the SHAMap.
  * @category Utilities
  */
-export function hashTxTree(transactions: LedgerTransactionExpanded[]): string {
+export function hashTxTree(transactions: LedgerTransactionExpandedV1[]): string {
   const shamap = new SHAMap()
   for (const txJSON of transactions) {
     const txBlobHex = encode(txJSON)
@@ -166,15 +168,17 @@ export function hashStateTree(entries: LedgerEntry[]): string {
 }
 
 /**
- * Normalize a v1 wrapped transaction to v2 flat format.
+ * Normalize a transaction to v1 flat format.
+ * Converts v2 wrapped format (tx_json + meta) to v1 flat format (fields directly on object with metaData).
  *
- * @param tx - The transaction to normalize.
- * @returns The normalized v2 transaction.
+ * @param tx - The transaction to normalize (can be v1 flat or v2 wrapped).
+ * @returns The normalized v1 flat transaction.
  */
-function normalizeToV2(
-  tx: LedgerTransactionExpanded | LedgerTransactionExpandedV1,
-): LedgerTransactionExpanded {
+function normalizeToV1(
+  tx: LedgerTransactionExpandedV1 | LedgerTransactionExpandedV2,
+): LedgerTransactionExpandedV1 {
   if ('tx_json' in tx) {
+    // v2 wrapped format: extract tx_json and meta, convert to v1 flat
     // Transaction union type cannot be spread directly (TS2698), so we
     // widen to a plain record first.
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- required to spread Transaction union
@@ -184,8 +188,9 @@ function normalizeToV2(
       ...txJson,
       hash: tx.hash,
       metaData: tx.meta,
-    } as LedgerTransactionExpanded
+    } as LedgerTransactionExpandedV1
   }
+  // already v1 flat format
   return tx
 }
 
@@ -203,17 +208,17 @@ function computeTransactionHash(
     throw new ValidationError('transactions is missing from the ledger')
   }
 
-  // Normalize transactions to the v2 flat format expected by hashTxTree.
+  // Normalize transactions to v1 flat format expected by hashTxTree.
   // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- ledger is a version union
   const txs = ledger.transactions as Array<
-    string | LedgerTransactionExpanded | LedgerTransactionExpandedV1
+    string | LedgerTransactionExpandedV1 | LedgerTransactionExpandedV2
   >
   const normalizedTransactions = txs
     .filter(
-      (tx): tx is LedgerTransactionExpanded | LedgerTransactionExpandedV1 =>
+      (tx): tx is LedgerTransactionExpandedV1 | LedgerTransactionExpandedV2 =>
         typeof tx !== 'string',
     )
-    .map(normalizeToV2)
+    .map(normalizeToV1)
 
   const transactionHash = hashTxTree(normalizedTransactions)