feat: add LTC cross-chain recovery support

Implement Litecoin address format conversion for cross-chain recovery
when LTC was sent to BTC addresses. This conversion allows the recovery
process to match LTC M-addresses with BTC 3-addresses stored in wallet.

Co-authored-by: llm-git <llm-git@ttll.de>

Ticket: BTC-2829

TICKET: BTC-2829

Author: lcovar

modules/abstract-utxo/src/recovery/crossChainRecovery.ts

@@ -113,6 +113,40 @@ export async function isWalletAddress(wallet: IWallet | WalletV1, address: strin
   }
 }
 
+/**
+ * Convert a Litecoin P2SH address from M... format (scriptHash 0x32) to the legacy 3... format (scriptHash 0x05).
+ * This is needed for cross-chain recovery when LTC was sent to a BTC address, because the BTC wallet
+ * stores addresses in the 3... format while the LTC blockchain returns addresses in M... format.
+ *
+ * @param address - LTC address to convert
+ * @param network - The Litecoin network
+ * @returns The address in legacy 3... format, or the original address if it's not a P2SH address
+ */
+function convertLtcAddressToLegacyFormat(address: string, network: utxolib.Network): string {
+  try {
+    // Try to decode as bech32 - these don't need conversion
+    utxolib.address.fromBech32(address);
+    return address;
+  } catch (e) {
+    // Not bech32, continue to base58
+  }
+
+  try {
+    const decoded = utxolib.address.fromBase58Check(address, network);
+    // Only convert P2SH addresses (scriptHash), not P2PKH (pubKeyHash)
+    if (decoded.version === network.scriptHash) {
+      // Convert to legacy format using Bitcoin's scriptHash (0x05)
+      const legacyScriptHash = utxolib.networks.bitcoin.scriptHash;
+      return utxolib.address.toBase58Check(decoded.hash, legacyScriptHash, network);
+    }
+    // P2PKH or other - return unchanged
+    return address;
+  } catch (e) {
+    // If decoding fails, return the original address
+    return address;
+  }
+}
+
 /**
  * @param coin
  * @param txid
@@ -137,7 +171,18 @@ async function getAllRecoveryOutputs<TNumber extends number | bigint = number>(
         // in non legacy format. However, we want to keep the address in the same format as the response since we
         // are going to hit the API again to fetch address unspents.
         const canonicalAddress = coin.canonicalAddress(output.address);
-        const isWalletOwned = await isWalletAddress(wallet, canonicalAddress);
+        let isWalletOwned = await isWalletAddress(wallet, canonicalAddress);
+
+        // For LTC cross-chain recovery: if the address isn't found, try the legacy format.
+        // When LTC is sent to a BTC address, the LTC blockchain returns M... addresses
+        // but the BTC wallet stores addresses in 3... format.
+        if (!isWalletOwned && coin.getFamily() === 'ltc') {
+          const legacyAddress = convertLtcAddressToLegacyFormat(output.address, coin.network);
+          if (legacyAddress !== output.address) {
+            isWalletOwned = await isWalletAddress(wallet, legacyAddress);
+          }
+        }
+
         return isWalletOwned ? output.address : null;
       })
     )

modules/abstract-utxo/test/unit/impl/ltc/unit/index.ts

@@ -1,10 +1,34 @@
 import 'should';
-
+import * as utxolib from '@bitgo/utxo-lib';
 import { TestBitGoAPI, TestBitGo } from '@bitgo/sdk-test';
 import { BitGoAPI } from '@bitgo/sdk-api';
 
 import { Ltc, Tltc } from '../../../../../src/impl/ltc';
 
+/**
+ * Helper to convert LTC M... address to legacy 3... format (same as in crossChainRecovery.ts)
+ * This is for testing purposes to verify the conversion logic works.
+ */
+function convertLtcAddressToLegacyFormat(address: string, network: utxolib.Network): string {
+  try {
+    utxolib.address.fromBech32(address);
+    return address;
+  } catch (e) {
+    // Not bech32
+  }
+
+  try {
+    const decoded = utxolib.address.fromBase58Check(address, network);
+    if (decoded.version === network.scriptHash) {
+      const legacyScriptHash = utxolib.networks.bitcoin.scriptHash;
+      return utxolib.address.toBase58Check(decoded.hash, legacyScriptHash, network);
+    }
+    return address;
+  } catch (e) {
+    return address;
+  }
+}
+
 describe('Litecoin:', function () {
   const bitgo: TestBitGoAPI = TestBitGo.decorate(BitGoAPI, { env: 'test' });
   bitgo.initializeTestVars();
@@ -14,6 +38,34 @@ describe('Litecoin:', function () {
   const ltc = bitgo.coin('ltc') as Ltc;
   const tltc = bitgo.coin('tltc') as Tltc;
 
+  describe('LTC to legacy address conversion (for cross-chain recovery)', () => {
+    it('should convert M... P2SH address to 3... legacy format', () => {
+      // These two addresses represent the same underlying script hash:
+      // - MNQ7zkgMsaV67rsjA3JuP59RC5wxRXpwgE is the LTC format (scriptHash 0x32)
+      // - 3GBygsGPvTdfKMbq4AKZZRu1sPMWPEsBfd is the BTC format (scriptHash 0x05)
+      const ltcAddress = 'MNQ7zkgMsaV67rsjA3JuP59RC5wxRXpwgE';
+      const expectedLegacyAddress = '3GBygsGPvTdfKMbq4AKZZRu1sPMWPEsBfd';
+
+      const legacyAddress = convertLtcAddressToLegacyFormat(ltcAddress, ltc.network);
+      legacyAddress.should.equal(expectedLegacyAddress);
+    });
+
+    it('should convert MD68PsdheKxcYsrVLyZRXgoSDLnB1MdVtE to legacy format', () => {
+      const address = 'MD68PsdheKxcYsrVLyZRXgoSDLnB1MdVtE';
+      const legacyAddress = convertLtcAddressToLegacyFormat(address, ltc.network);
+
+      // Should start with '3' (legacy BTC P2SH format)
+      legacyAddress.should.startWith('3');
+      console.log(`${address} -> ${legacyAddress}`);
+    });
+
+    it('should not modify bech32 addresses', () => {
+      const bech32Address = 'ltc1qgrl8zpndsklaa9swgd5vevyxmx5x63vcrl7dk4';
+      const result = convertLtcAddressToLegacyFormat(bech32Address, ltc.network);
+      result.should.equal(bech32Address);
+    });
+  });
+
   describe('should validate addresses', () => {
     it('should validate base58 addresses', () => {
       // known valid main and testnet base58 address are valid