feat(abstract-utxo): migrate inscription builder to wasm-utxo

Replace utxo-lib with wasm-utxo implementation for inscription handling.
This provides a more efficient and robust way to create and sign
inscription transactions using WebAssembly.

Key changes:
- Replace utxo-lib dependency with wasm-utxo in inscription functions
- Update API to use typed arrays instead of Node Buffers
- Add coin name mapping for different Bitcoin networks
- Improve error handling and type safety

Issue: BTC-2936

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

Author: OttoAllmendinger

modules/abstract-utxo/src/impl/btc/inscriptionBuilder.ts

@@ -11,7 +11,6 @@ import {
   xprvToRawPrv,
   xpubToCompressedPub,
 } from '@bitgo/sdk-core';
-import * as utxolib from '@bitgo/utxo-lib';
 import {
   createPsbtForSingleInscriptionPassingTransaction,
   DefaultInscriptionConstraints,
@@ -23,13 +22,39 @@ import {
   findOutputLayoutForWalletUnspents,
   MAX_UNSPENTS_FOR_OUTPUT_LAYOUT,
   SatPoint,
+  WalletUnspent,
+  type TapLeafScript,
 } from '@bitgo/utxo-ord';
+import { fixedScriptWallet, type CoinName } from '@bitgo/wasm-utxo';
 
-import { AbstractUtxoCoin, RootWalletKeys } from '../../abstractUtxoCoin';
-import { getWalletKeys } from '../../recovery/crossChainRecovery';
+import { AbstractUtxoCoin } from '../../abstractUtxoCoin';
+
+/** Key identifier for signing */
+type SignerKey = 'user' | 'backup' | 'bitgo';
+
+/** Unspent from wallet API (value may be number or bigint) */
+type WalletUnspentLike = {
+  id: string;
+  value: number | bigint;
+  chain: number;
+  index: number;
+};
+
+const { RootWalletKeys: WasmRootWalletKeys } = fixedScriptWallet;
 
 const SUPPLEMENTARY_UNSPENTS_MIN_VALUE_SATS = [0, 20_000, 200_000];
 
+/** Map coin chain to CoinName for wasm-utxo */
+function getCoinName(coin: AbstractUtxoCoin): CoinName {
+  const chain = coin.getChain();
+  // CoinName matches the chain name for Bitcoin
+  const validCoins: CoinName[] = ['btc', 'tbtc', 'tbtc4', 'tbtcsig', 'tbtcbgsig'];
+  if (validCoins.includes(chain as CoinName)) {
+    return chain as CoinName;
+  }
+  throw new Error(`Unsupported coin for inscriptions: ${chain}`);
+}
+
 export class InscriptionBuilder implements IInscriptionBuilder {
   private readonly wallet: IWallet;
   private readonly coin: AbstractUtxoCoin;
@@ -45,9 +70,21 @@ export class InscriptionBuilder implements IInscriptionBuilder {
 
     const derived = this.coin.deriveKeyWithSeed({ key: user.pub, seed: inscriptionData.toString() });
     const compressedPublicKey = xpubToCompressedPub(derived.key);
-    const xOnlyPublicKey = utxolib.bitgo.outputScripts.toXOnlyPublicKey(Buffer.from(compressedPublicKey, 'hex'));
+    const xOnlyPublicKey = Buffer.from(compressedPublicKey, 'hex').subarray(1); // Remove parity byte
 
-    return inscriptions.createInscriptionRevealData(xOnlyPublicKey, contentType, inscriptionData, this.coin.network);
+    const coinName = getCoinName(this.coin);
+    const result = inscriptions.createInscriptionRevealData(xOnlyPublicKey, contentType, inscriptionData, coinName);
+
+    // Convert TapLeafScript to utxolib format for backwards compatibility
+    return {
+      address: result.address,
+      revealTransactionVSize: result.revealTransactionVSize,
+      tapLeafScript: {
+        controlBlock: Buffer.from(result.tapLeafScript.controlBlock),
+        script: Buffer.from(result.tapLeafScript.script),
+        leafVersion: result.tapLeafScript.leafVersion,
+      },
+    };
   }
 
   private async prepareTransferWithExtraInputs(
@@ -59,36 +96,42 @@ export class InscriptionBuilder implements IInscriptionBuilder {
       inscriptionConstraints,
       txFormat,
     }: {
-      signer: utxolib.bitgo.KeyName;
-      cosigner: utxolib.bitgo.KeyName;
+      signer: SignerKey;
+      cosigner: SignerKey;
       inscriptionConstraints: {
         minChangeOutput?: bigint;
         minInscriptionOutput?: bigint;
         maxInscriptionOutput?: bigint;
       };
       txFormat?: 'psbt' | 'legacy';
     },
-    rootWalletKeys: RootWalletKeys,
+    rootWalletKeys: fixedScriptWallet.RootWalletKeys,
     outputs: InscriptionOutputs,
-    inscriptionUnspents: utxolib.bitgo.WalletUnspent<bigint>[],
+    inscriptionUnspents: WalletUnspent[],
     supplementaryUnspentsMinValue: number
   ): Promise<PrebuildTransactionResult> {
-    let supplementaryUnspents: utxolib.bitgo.WalletUnspent<bigint>[] = [];
+    let supplementaryUnspents: WalletUnspent[] = [];
     if (supplementaryUnspentsMinValue > 0) {
       const response = await this.wallet.unspents({
         minValue: supplementaryUnspentsMinValue,
       });
       // Filter out the inscription unspent from the supplementary unspents
       supplementaryUnspents = response.unspents
-        .filter((unspent) => unspent.id !== inscriptionUnspents[0].id)
+        .filter((unspent: { id: string }) => unspent.id !== inscriptionUnspents[0].id)
         .slice(0, MAX_UNSPENTS_FOR_OUTPUT_LAYOUT - 1)
-        .map((unspent) => {
-          unspent.value = BigInt(unspent.value);
-          return unspent;
-        });
+        .map(
+          (unspent: WalletUnspentLike): WalletUnspent => ({
+            id: unspent.id,
+            value: BigInt(unspent.value),
+            chain: unspent.chain,
+            index: unspent.index,
+          })
+        );
     }
+
+    const coinName = getCoinName(this.coin);
     const psbt = createPsbtForSingleInscriptionPassingTransaction(
-      this.coin.network,
+      coinName,
       {
         walletKeys: rootWalletKeys,
         signer,
@@ -117,7 +160,7 @@ export class InscriptionBuilder implements IInscriptionBuilder {
     }
     return {
       walletId: this.wallet.id(),
-      txHex: txFormat === 'psbt' ? psbt.toHex() : psbt.getUnsignedTx().toHex(),
+      txHex: Buffer.from(psbt.serialize()).toString('hex'),
       txInfo: { unspents: allUnspents },
       feeInfo: { fee: Number(outputLayout.layout.feeOutput), feeString: outputLayout.layout.feeOutput.toString() },
     };
@@ -146,27 +189,36 @@ export class InscriptionBuilder implements IInscriptionBuilder {
       changeAddressType = 'p2wsh',
       txFormat = 'psbt',
     }: {
-      signer?: utxolib.bitgo.KeyName;
-      cosigner?: utxolib.bitgo.KeyName;
+      signer?: SignerKey;
+      cosigner?: SignerKey;
       inscriptionConstraints?: {
         minChangeOutput?: bigint;
         minInscriptionOutput?: bigint;
         maxInscriptionOutput?: bigint;
       };
-      changeAddressType?: utxolib.bitgo.outputScripts.ScriptType2Of3;
+      changeAddressType?: 'p2sh' | 'p2shP2wsh' | 'p2wsh' | 'p2tr' | 'p2trMusig2';
       txFormat?: 'psbt' | 'legacy';
     }
   ): Promise<PrebuildTransactionResult> {
     assert(isSatPoint(satPoint));
 
-    const rootWalletKeys = await getWalletKeys(this.coin, this.wallet);
+    const rootWalletKeys = await this.getWasmWalletKeys();
     const parsedSatPoint = parseSatPoint(satPoint);
     const transaction = await this.wallet.getTransaction({ txHash: parsedSatPoint.txid });
-    const unspents: utxolib.bitgo.WalletUnspent<bigint>[] = [transaction.outputs[parsedSatPoint.vout]];
-    unspents[0].value = BigInt(unspents[0].value);
+    const output = transaction.outputs[parsedSatPoint.vout];
+    const unspents: WalletUnspent[] = [
+      {
+        id: `${parsedSatPoint.txid}:${parsedSatPoint.vout}`,
+        value: BigInt(output.value),
+        chain: output.chain,
+        index: output.index,
+      },
+    ];
+
+    const changeChain = fixedScriptWallet.ChainCode.value(changeAddressType, 'internal');
 
     const changeAddress = await this.wallet.createAddress({
-      chain: utxolib.bitgo.getInternalChainCode(changeAddressType),
+      chain: changeChain,
     });
     const outputs: InscriptionOutputs = {
       inscriptionRecipient: recipient,
@@ -197,6 +249,22 @@ export class InscriptionBuilder implements IInscriptionBuilder {
     throw new Error('Fee too high for the selected unspent with this fee rate'); // Exhausted all tries to supplement
   }
 
+  /**
+   * Get wallet keys as wasm-utxo RootWalletKeys
+   */
+  private async getWasmWalletKeys(): Promise<fixedScriptWallet.RootWalletKeys> {
+    const keychainIds = this.wallet.keyIds();
+    const [user, backup, bitgo] = await Promise.all([
+      this.wallet.baseCoin.keychains().get({ id: keychainIds[KeyIndices.USER] }),
+      this.wallet.baseCoin.keychains().get({ id: keychainIds[KeyIndices.BACKUP] }),
+      this.wallet.baseCoin.keychains().get({ id: keychainIds[KeyIndices.BITGO] }),
+    ]);
+
+    assert(user.pub && backup.pub && bitgo.pub, 'Missing wallet public keys');
+
+    return WasmRootWalletKeys.from([user.pub, backup.pub, bitgo.pub]);
+  }
+
   /**
    *
    * @param walletPassphrase
@@ -209,10 +277,10 @@ export class InscriptionBuilder implements IInscriptionBuilder {
    */
   async signAndSendReveal(
     walletPassphrase: string,
-    tapLeafScript: utxolib.bitgo.TapLeafScript,
+    tapLeafScript: TapLeafScript,
     commitAddress: string,
     unsignedCommitTx: Buffer,
-    commitTransactionUnspents: utxolib.bitgo.WalletUnspent[],
+    commitTransactionUnspents: WalletUnspentLike[],
     recipientAddress: string,
     inscriptionData: Buffer
   ): Promise<SubmitTransactionResponse> {
@@ -230,19 +298,20 @@ export class InscriptionBuilder implements IInscriptionBuilder {
     const derived = this.coin.deriveKeyWithSeed({ key: xprv, seed: inscriptionData.toString() });
     const prv = xprvToRawPrv(derived.key);
 
-    const fullySignedRevealTransaction = await inscriptions.signRevealTransaction(
+    const coinName = getCoinName(this.coin);
+    const fullySignedRevealTransaction = inscriptions.signRevealTransaction(
       Buffer.from(prv, 'hex'),
       tapLeafScript,
       commitAddress,
       recipientAddress,
       Buffer.from(halfSignedCommitTransaction.txHex, 'hex'),
-      this.coin.network
+      coinName
     );
 
     return this.wallet.submitTransaction({
       halfSigned: {
         txHex: halfSignedCommitTransaction.txHex,
-        signedChildPsbt: fullySignedRevealTransaction.toHex(),
+        signedChildPsbt: Buffer.from(fullySignedRevealTransaction).toString('hex'),
       },
     });
   }

modules/utxo-ord/package.json

@@ -28,8 +28,9 @@
     "directory": "modules/utxo-ord"
   },
   "dependencies": {
-    "@bitgo/sdk-core": "^36.27.0",
-    "@bitgo/unspents": "^0.50.14",
+    "@bitgo/wasm-utxo": "^1.27.0"
+  },
+  "devDependencies": {
     "@bitgo/utxo-lib": "^11.19.1"
   },
   "lint-staged": {

modules/utxo-ord/src/SatPoint.ts

@@ -9,10 +9,29 @@ https://github.com/casey/ord/blob/master/bip.mediawiki#terminology-and-notation
 > `680df1e4d43016571e504b0b142ee43c5c0b83398a97bdcfd94ea6f287322d22:0:6`
 
 */
-import { bitgo } from '@bitgo/utxo-lib';
 
 export type SatPoint = `${string}:${number}:${bigint}`;
 
+/**
+ * Parse an output ID (txid:vout) into its components.
+ */
+export function parseOutputId(outputId: string): { txid: string; vout: number } {
+  const colonIndex = outputId.lastIndexOf(':');
+  if (colonIndex === -1) {
+    throw new Error(`Invalid output id format: missing colon`);
+  }
+  const txid = outputId.slice(0, colonIndex);
+  const voutStr = outputId.slice(colonIndex + 1);
+  if (txid.length !== 64 || !/^[0-9a-fA-F]+$/.test(txid)) {
+    throw new Error(`Invalid txid: must be 64 hex characters`);
+  }
+  const vout = parseInt(voutStr, 10);
+  if (isNaN(vout) || vout < 0) {
+    throw new Error(`Invalid vout: must be non-negative integer`);
+  }
+  return { txid, vout };
+}
+
 export function parseSatPoint(p: SatPoint): { txid: string; vout: number; offset: bigint } {
   const parts = p.split(':');
   if (parts.length !== 3) {
@@ -27,7 +46,7 @@ export function parseSatPoint(p: SatPoint): { txid: string; vout: number; offset
     throw new Error(`SatPoint offset must be positive`);
   }
   return {
-    ...bitgo.parseOutputId([txid, vout].join(':')),
+    ...parseOutputId([txid, vout].join(':')),
     offset,
   };
 }

modules/utxo-ord/src/index.ts

@@ -8,3 +8,5 @@ export * from './OutputLayout';
 export * from './SatPoint';
 export * from './psbt';
 export * as inscriptions from './inscriptions';
+export type { TapLeafScript, PreparedInscriptionRevealData } from './inscriptions';
+export type { WalletUnspent } from './psbt';