feat(abstract-utxo): use wasm-utxo for backup key recovery

OttoAllmendinger · llm-git · OttoAllmendinger · commit b14a3693e188 · 2026-02-04T13:40:45.000+01:00
Refactor the backup key recovery flow to use WASM primitives instead of utxolib. Issue: BTC-2891 Co-authored-by: llm-git <llm-git@ttll.de>
diff --git a/modules/abstract-utxo/src/recovery/backupKeyRecovery.ts b/modules/abstract-utxo/src/recovery/backupKeyRecovery.ts
@@ -1,5 +1,4 @@
 import _ from 'lodash';
-import * as utxolib from '@bitgo/utxo-lib';
 import {
   BitGoBase,
   ErrorNoInputToRecover,
@@ -9,32 +8,29 @@ import {
   getIsUnsignedSweep,
   isTriple,
   krsProviders,
+  Triple,
 } from '@bitgo/sdk-core';
-import { getMainnet, networks } from '@bitgo/utxo-lib';
-import { fixedScriptWallet } from '@bitgo/wasm-utxo';
+import { BIP32, fixedScriptWallet } from '@bitgo/wasm-utxo';
 
 import { AbstractUtxoCoin } from '../abstractUtxoCoin';
 import { signAndVerifyPsbt } from '../transaction/fixedScript/signTransaction';
 import { generateAddressWithChainAndIndex } from '../address';
 import { encodeTransaction } from '../transaction/decode';
 import { getReplayProtectionPubkeys } from '../transaction/fixedScript/replayProtection';
-import { UtxoCoinName } from '../names';
-import type { WalletUnspent } from '../unspent';
+import { getMainnetCoinName, UtxoCoinName } from '../names';
+import { parseOutputId, unspentSum, type WalletUnspent } from '../unspent';
 
 import { forCoin, RecoveryProvider } from './RecoveryProvider';
 import { MempoolApi } from './mempoolApi';
 import { CoingeckoApi } from './coingeckoApi';
 import { createBackupKeyRecoveryPsbt, getRecoveryAmount } from './psbt';
 
-type ScriptType2Of3 = utxolib.bitgo.outputScripts.ScriptType2Of3;
-type ChainCode = utxolib.bitgo.ChainCode;
-type RootWalletKeys = utxolib.bitgo.RootWalletKeys;
+type ScriptType2Of3 = fixedScriptWallet.OutputScriptType;
+type ChainCode = fixedScriptWallet.ChainCode;
 type WalletUnspentJSON = WalletUnspent & {
   valueString: string;
 };
 
-const { getInternalChainCode, scriptTypeForChain, outputScripts, getExternalChainCode } = utxolib.bitgo;
-
 // V1 only deals with BTC. 50 sat/vbyte is very arbitrary.
 export const DEFAULT_RECOVERY_FEERATE_SAT_VBYTE_V1 = 50;
 
@@ -120,7 +116,7 @@ export interface RecoverParams {
 function getFormattedAddress(
   coin: AbstractUtxoCoin,
   coinName: UtxoCoinName,
-  walletKeys: RootWalletKeys,
+  walletKeys: fixedScriptWallet.RootWalletKeys,
   chain: ChainCode,
   addrIndex: number
 ): string {
@@ -131,15 +127,18 @@ function getFormattedAddress(
   return format === 'cashaddr' ? address.split(':')[1] : address;
 }
 
+function hasWitnessData(scriptType: ScriptType2Of3): boolean {
+  return scriptType !== 'p2sh';
+}
+
 async function queryBlockchainUnspentsPath(
   coin: AbstractUtxoCoin,
   params: RecoverParams,
-  walletKeys: RootWalletKeys,
+  walletKeys: fixedScriptWallet.RootWalletKeys,
   chain: ChainCode
 ): Promise<WalletUnspent<bigint>[]> {
-  const scriptType = scriptTypeForChain(chain);
-  const fetchPrevTx =
-    !utxolib.bitgo.outputScripts.hasWitnessData(scriptType) && getMainnet(coin.network) !== networks.zcash;
+  const scriptType = fixedScriptWallet.ChainCode.scriptType(chain);
+  const fetchPrevTx = !hasWitnessData(scriptType) && getMainnetCoinName(coin.name) !== 'zec';
   const recoveryProvider = params.recoveryProvider ?? forCoin(coin.getChain(), params.apiKey);
   const MAX_SEQUENTIAL_ADDRESSES_WITHOUT_TXS = params.scan || 20;
   let numSequentialAddressesWithoutTxs = 0;
@@ -168,7 +167,7 @@ async function queryBlockchainUnspentsPath(
         const addressUnspents = await recoveryProvider.getUnspentsForAddresses([formattedAddress]);
         const processedUnspents = await Promise.all(
           addressUnspents.map(async (u): Promise<WalletUnspent<bigint>> => {
-            const { txid, vout } = utxolib.bitgo.parseOutputId(u.id);
+            const { txid, vout } = parseOutputId(u.id);
             let val = BigInt(u.value);
             if (coin.amountType === 'bigint') {
               // blockchair returns the number with the correct precision, but in number format
@@ -246,6 +245,14 @@ export type BackupKeyRecoveryTransansaction = {
   recoveryAmountString: string;
 };
 
+function getBip32Privkeys(bitgo: BitGoBase, params: RecoverParams): Triple<BIP32> {
+  const keys = getBip32Keys(bitgo, params, { requireBitGoXpub: true });
+  if (!isTriple(keys)) {
+    throw new Error(`expected key triple`);
+  }
+  return keys.map((k) => BIP32.from(k.toBase58())) as Triple<BIP32>;
+}
+
 /**
  * Builds a funds recovery transaction without BitGo.
  *
@@ -303,35 +310,43 @@ export async function backupKeyRecovery(
   const krsProvider = isKrsRecovery ? getKrsProvider(coin, params.krsProvider) : undefined;
 
   // check whether key material and password authenticate the users and return parent keys of all three keys of the wallet
-  const keys = getBip32Keys(bitgo, params, { requireBitGoXpub: true });
-  if (!isTriple(keys)) {
-    throw new Error(`expected key triple`);
-  }
-  const walletKeys = new utxolib.bitgo.RootWalletKeys(keys, [
-    params.userKeyPath || utxolib.bitgo.RootWalletKeys.defaultPrefix,
-    utxolib.bitgo.RootWalletKeys.defaultPrefix,
-    utxolib.bitgo.RootWalletKeys.defaultPrefix,
-  ]);
+  const keys = getBip32Privkeys(bitgo, params);
+  const walletKeys = fixedScriptWallet.RootWalletKeys.from({
+    triple: keys,
+    derivationPrefixes: [params.userKeyPath || 'm/0/0', 'm/0/0', 'm/0/0'],
+  });
 
   const unspents: WalletUnspent<bigint>[] = (
     await Promise.all(
-      outputScripts.scriptTypes2Of3
+      fixedScriptWallet.outputScriptTypes
         .filter(
-          (addressType) => coin.supportsAddressType(addressType) && !params.ignoreAddressTypes?.includes(addressType)
+          (addressType) =>
+            fixedScriptWallet.supportsScriptType(coin.name, addressType) &&
+            !params.ignoreAddressTypes?.includes(addressType)
         )
         .reduce(
           (queries, addressType) => [
             ...queries,
-            queryBlockchainUnspentsPath(coin, params, walletKeys, getExternalChainCode(addressType)),
-            queryBlockchainUnspentsPath(coin, params, walletKeys, getInternalChainCode(addressType)),
+            queryBlockchainUnspentsPath(
+              coin,
+              params,
+              walletKeys,
+              fixedScriptWallet.ChainCode.value(addressType, 'external')
+            ),
+            queryBlockchainUnspentsPath(
+              coin,
+              params,
+              walletKeys,
+              fixedScriptWallet.ChainCode.value(addressType, 'internal')
+            ),
           ],
           [] as Promise<WalletUnspent<bigint>[]>[]
         )
     )
   ).flat();
 
   // Execute the queries and gather the unspents
-  const totalInputAmount = utxolib.bitgo.unspentSum(unspents, 'bigint');
+  const totalInputAmount = unspentSum(unspents);
   if (totalInputAmount <= BigInt(0)) {
     throw new ErrorNoInputToRecover();
   }
@@ -390,7 +405,7 @@ export async function backupKeyRecovery(
   const replayProtection = { publicKeys: getReplayProtectionPubkeys(coin.name) };
 
   // Sign with user key first
-  psbt = signAndVerifyPsbt(psbt, walletKeys.user, rootWalletKeysWasm, replayProtection);
+  psbt = signAndVerifyPsbt(psbt, keys[0], rootWalletKeysWasm, replayProtection);
 
   if (isKrsRecovery) {
     // The KRS provider keyternal solely supports P2SH, P2WSH, and P2SH-P2WSH input script types.
@@ -403,7 +418,7 @@ export async function backupKeyRecovery(
         : encodeTransaction(psbt).toString('hex');
   } else {
     // Sign with backup key
-    psbt = signAndVerifyPsbt(psbt, walletKeys.backup, rootWalletKeysWasm, replayProtection);
+    psbt = signAndVerifyPsbt(psbt, keys[1], rootWalletKeysWasm, replayProtection);
     // Finalize and extract transaction
     psbt.finalizeAllInputs();
     txInfo.transactionHex = Buffer.from(psbt.extractTransaction().toBytes()).toString('hex');
diff --git a/modules/abstract-utxo/src/recovery/crossChainRecovery.ts b/modules/abstract-utxo/src/recovery/crossChainRecovery.ts
@@ -341,7 +341,7 @@ async function getPrv(xprv?: string, passphrase?: string, wallet?: IWallet | Wal
  */
 function createSweepTransaction<TNumber extends number | bigint = number>(
   coinName: CoinName,
-  walletKeys: RootWalletKeys,
+  walletKeys: fixedScriptWallet.RootWalletKeys,
   unspents: WalletUnspent<TNumber>[],
   targetAddress: string,
   feeRateSatVB: number
@@ -410,7 +410,7 @@ export async function recoverCrossChain<TNumber extends number | bigint = number
     params.apiKey
   );
   const walletUnspents = await toWalletUnspents<TNumber>(params.sourceCoin, params.recoveryCoin, unspents, wallet);
-  const walletKeys = await getWalletKeys(params.recoveryCoin, wallet);
+  const walletKeys = fixedScriptWallet.RootWalletKeys.from(await getWalletKeys(params.recoveryCoin, wallet));
   const prv =
     params.xprv || params.walletPassphrase ? await getPrv(params.xprv, params.walletPassphrase, wallet) : undefined;
   const feeRateSatVB = await getFeeRateSatVB(params.sourceCoin);
@@ -435,7 +435,7 @@ export async function recoverCrossChain<TNumber extends number | bigint = number
   }
 
   // For signed recovery, sign the PSBT with user key and return half-signed PSBT
-  psbt = signAndVerifyPsbt(psbt, prv, fixedScriptWallet.RootWalletKeys.from(walletKeys), {
+  psbt = signAndVerifyPsbt(psbt, prv, walletKeys, {
     publicKeys: getReplayProtectionPubkeys(params.sourceCoin.name),
   });
 
diff --git a/modules/abstract-utxo/src/recovery/psbt.ts b/modules/abstract-utxo/src/recovery/psbt.ts
@@ -1,22 +1,13 @@
-import * as utxolib from '@bitgo/utxo-lib';
 import { CoinName, fixedScriptWallet, address as wasmAddress } from '@bitgo/wasm-utxo';
 
-import { getNetworkFromCoinName } from '../names';
-import type { WalletUnspent } from '../unspent';
-
-type RootWalletKeys = utxolib.bitgo.RootWalletKeys;
-
-const { chainCodesP2tr, chainCodesP2trMusig2 } = utxolib.bitgo;
-
-type ChainCode = utxolib.bitgo.ChainCode;
+import { parseOutputId, unspentSum, type WalletUnspent } from '../unspent';
 
 /**
  * Check if a chain code is for a taproot script type
  */
-export function isTaprootChain(chain: ChainCode): boolean {
-  return (
-    (chainCodesP2tr as readonly number[]).includes(chain) || (chainCodesP2trMusig2 as readonly number[]).includes(chain)
-  );
+export function isTaprootChain(chain: fixedScriptWallet.ChainCode): boolean {
+  const scriptType = fixedScriptWallet.ChainCode.scriptType(chain);
+  return scriptType === 'p2trLegacy' || scriptType === 'p2trMusig2';
 }
 
 class InsufficientFundsError extends Error {
@@ -81,7 +72,7 @@ export interface CreateEmptyWasmPsbtOptions {
  */
 export function createEmptyWasmPsbt(
   coinName: CoinName,
-  rootWalletKeys: RootWalletKeys,
+  rootWalletKeys: fixedScriptWallet.RootWalletKeys,
   options?: CreateEmptyWasmPsbtOptions
 ): fixedScriptWallet.BitGoPsbt {
   if (isZcash(coinName)) {
@@ -106,10 +97,10 @@ export function createEmptyWasmPsbt(
 export function addWalletInputsToWasmPsbt(
   wasmPsbt: fixedScriptWallet.BitGoPsbt,
   unspents: WalletUnspent<bigint>[],
-  rootWalletKeys: RootWalletKeys
+  rootWalletKeys: fixedScriptWallet.RootWalletKeys
 ): void {
   unspents.forEach((unspent) => {
-    const { txid, vout } = utxolib.bitgo.parseOutputId(unspent.id);
+    const { txid, vout } = parseOutputId(unspent.id);
     const signPath: fixedScriptWallet.SignPath | undefined = isTaprootChain(unspent.chain)
       ? { signer: 'user', cosigner: 'backup' }
       : undefined;
@@ -152,30 +143,12 @@ export function addOutputToWasmPsbt(
   return wasmPsbt.addOutput({ script, value });
 }
 
-/**
- * Convert a wasm-utxo BitGoPsbt to a utxolib UtxoPsbt.
- *
- * @param wasmPsbt - The wasm-utxo BitGoPsbt to convert
- * @param network - The network
- * @returns A utxolib UtxoPsbt
- */
-export function toPsbtToUtxolibPsbt(
-  wasmPsbt: fixedScriptWallet.BitGoPsbt | utxolib.bitgo.UtxoPsbt,
-  coinName: CoinName
-): utxolib.bitgo.UtxoPsbt {
-  if (wasmPsbt instanceof fixedScriptWallet.BitGoPsbt) {
-    const network = getNetworkFromCoinName(coinName);
-    return utxolib.bitgo.createPsbtFromBuffer(Buffer.from(wasmPsbt.serialize()), network);
-  }
-  return wasmPsbt;
-}
-
 /**
  * Create a backup key recovery PSBT using wasm-utxo
  */
 function createBackupKeyRecoveryPsbtWasm(
   coinName: CoinName,
-  rootWalletKeys: RootWalletKeys,
+  rootWalletKeys: fixedScriptWallet.RootWalletKeys,
   unspents: WalletUnspent<bigint>[],
   options: CreateBackupKeyRecoveryPsbtOptions
 ): fixedScriptWallet.BitGoPsbt {
@@ -195,7 +168,7 @@ function createBackupKeyRecoveryPsbtWasm(
   }
 
   const approximateFee = BigInt(dimensions.getVSize() * feeRateSatVB);
-  const totalInputAmount = utxolib.bitgo.unspentSum(unspents, 'bigint');
+  const totalInputAmount = unspentSum(unspents);
   const recoveryAmount = totalInputAmount - approximateFee - keyRecoveryServiceFee;
 
   if (recoveryAmount < BigInt(0)) {
@@ -222,7 +195,7 @@ function createBackupKeyRecoveryPsbtWasm(
  */
 export function createBackupKeyRecoveryPsbt(
   coinName: CoinName,
-  rootWalletKeys: RootWalletKeys,
+  rootWalletKeys: fixedScriptWallet.RootWalletKeys,
   unspents: WalletUnspent<bigint>[],
   options: CreateBackupKeyRecoveryPsbtOptions
 ): fixedScriptWallet.BitGoPsbt {
@@ -235,7 +208,7 @@ export function createBackupKeyRecoveryPsbt(
 
 export function getRecoveryAmount(
   psbt: fixedScriptWallet.BitGoPsbt,
-  walletKeys: RootWalletKeys,
+  walletKeys: fixedScriptWallet.RootWalletKeys,
   address: string
 ): bigint {
   const parsedOutputs = psbt.parseOutputsWithWalletKeys(walletKeys);
diff --git a/modules/abstract-utxo/src/transaction/fixedScript/signPsbtUtxolib.ts b/modules/abstract-utxo/src/transaction/fixedScript/signPsbtUtxolib.ts
@@ -35,7 +35,7 @@ export type PsbtParsedScriptType =
  */
 export function signAndVerifyPsbt(
   psbt: utxolib.bitgo.UtxoPsbt,
-  signerKeychain: utxolib.BIP32Interface
+  signerKeychain: BIP32Interface
 ): utxolib.bitgo.UtxoPsbt {
   const txInputs = psbt.txInputs;
   const outputIds: string[] = [];
diff --git a/modules/abstract-utxo/src/transaction/fixedScript/signPsbtWasm.ts b/modules/abstract-utxo/src/transaction/fixedScript/signPsbtWasm.ts
@@ -1,7 +1,7 @@
 import assert from 'assert';
 
 import { BIP32Interface } from '@bitgo/utxo-lib';
-import { ECPair, fixedScriptWallet } from '@bitgo/wasm-utxo';
+import { BIP32, ECPair, fixedScriptWallet } from '@bitgo/wasm-utxo';
 
 import { toWasmBIP32 } from '../../wasmUtil';
 
@@ -36,7 +36,7 @@ function hasKeyPathSpendInput(
  */
 export function signAndVerifyPsbtWasm(
   tx: fixedScriptWallet.BitGoPsbt,
-  signerKeychain: BIP32Interface,
+  signerKeychain: BIP32Interface | BIP32,
   rootWalletKeys: fixedScriptWallet.RootWalletKeys,
   replayProtection: ReplayProtectionKeys
 ): fixedScriptWallet.BitGoPsbt {
diff --git a/modules/abstract-utxo/src/transaction/fixedScript/signTransaction.ts b/modules/abstract-utxo/src/transaction/fixedScript/signTransaction.ts
@@ -5,7 +5,7 @@ import _ from 'lodash';
 import { BIP32Interface } from '@bitgo/secp256k1';
 import { bitgo } from '@bitgo/utxo-lib';
 import * as utxolib from '@bitgo/utxo-lib';
-import { fixedScriptWallet } from '@bitgo/wasm-utxo';
+import { BIP32, fixedScriptWallet } from '@bitgo/wasm-utxo';
 
 import { UtxoCoinName } from '../../names';
 import type { Unspent } from '../../unspent';
@@ -21,35 +21,37 @@ import { getReplayProtectionPubkeys } from './replayProtection';
  */
 export function signAndVerifyPsbt(
   psbt: utxolib.bitgo.UtxoPsbt,
-  signerKeychain: BIP32Interface,
+  signerKeychain: BIP32Interface | BIP32,
   rootWalletKeys: fixedScriptWallet.RootWalletKeys | undefined,
   replayProtection: ReplayProtectionKeys | undefined
 ): utxolib.bitgo.UtxoPsbt;
 export function signAndVerifyPsbt(
   psbt: fixedScriptWallet.BitGoPsbt,
-  signerKeychain: BIP32Interface,
+  signerKeychain: BIP32Interface | BIP32,
   rootWalletKeys: fixedScriptWallet.RootWalletKeys,
   replayProtection: ReplayProtectionKeys
 ): fixedScriptWallet.BitGoPsbt;
 export function signAndVerifyPsbt(
   psbt: utxolib.bitgo.UtxoPsbt | fixedScriptWallet.BitGoPsbt,
-  signerKeychain: BIP32Interface,
+  signerKeychain: BIP32Interface | BIP32,
   rootWalletKeys: fixedScriptWallet.RootWalletKeys,
   replayProtection: ReplayProtectionKeys
 ): utxolib.bitgo.UtxoPsbt | fixedScriptWallet.BitGoPsbt;
 export function signAndVerifyPsbt(
   psbt: utxolib.bitgo.UtxoPsbt | fixedScriptWallet.BitGoPsbt,
-  signerKeychain: BIP32Interface,
+  signerKeychain: BIP32Interface | BIP32,
   rootWalletKeys: fixedScriptWallet.RootWalletKeys | undefined,
   replayProtection: ReplayProtectionKeys | undefined
 ): utxolib.bitgo.UtxoPsbt | fixedScriptWallet.BitGoPsbt {
   if (psbt instanceof bitgo.UtxoPsbt) {
+    if (signerKeychain instanceof BIP32) {
+      signerKeychain = utxolib.bip32.fromBase58(signerKeychain.toBase58());
+    }
     return signAndVerifyPsbtUtxolib(psbt, signerKeychain);
-  } else {
-    assert(rootWalletKeys, 'rootWalletKeys required for wasm-utxo signing');
-    assert(replayProtection, 'replayProtection required for wasm-utxo signing');
-    return signAndVerifyPsbtWasm(psbt, signerKeychain, rootWalletKeys, replayProtection);
   }
+  assert(rootWalletKeys, 'rootWalletKeys required for wasm-utxo signing');
+  assert(replayProtection, 'replayProtection required for wasm-utxo signing');
+  return signAndVerifyPsbtWasm(psbt, signerKeychain, rootWalletKeys, replayProtection);
 }
 
 export async function signTransaction<
diff --git a/modules/abstract-utxo/src/unspent.ts b/modules/abstract-utxo/src/unspent.ts
