Merge pull request #5973 from BitGo/BTC-2032.backport-babylon

feat(utxo-staking): add BIP-322 support for Babylon staking

Author: OttoAllmendinger

modules/babylonlabs-io-btc-staking-ts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitgo/babylonlabs-io-btc-staking-ts",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "Library exposing methods for the creation and consumption of Bitcoin transactions pertaining to Babylon's Bitcoin Staking protocol.",
   "module": "dist/index.js",
   "main": "dist/index.cjs",

modules/babylonlabs-io-btc-staking-ts/src/staking/manager.ts

@@ -2,36 +2,53 @@ import { networks, Psbt, Transaction } from "bitcoinjs-lib";
 import { StakingParams, VersionedStakingParams } from "../types/params";
 import { TransactionResult, UTXO } from "../types";
 import { StakerInfo, Staking } from ".";
-import { fromBech32 } from "@cosmjs/encoding";
 import {
   btccheckpoint,
   btcstaking,
   btcstakingtx,
 } from "@babylonlabs-io/babylon-proto-ts";
 import {
+  BIP322Sig,
   BTCSigType,
   ProofOfPossessionBTC,
 } from "@babylonlabs-io/babylon-proto-ts/dist/generated/babylon/btcstaking/v1/pop";
 import { BABYLON_REGISTRY_TYPE_URLS } from "../constants/registry";
 import { createCovenantWitness } from "./transactions";
 import { getBabylonParamByBtcHeight, getBabylonParamByVersion } from "../utils/staking/param";
-import { reverseBuffer, uint8ArrayToHex } from "../utils";
+import { reverseBuffer } from "../utils";
 import { deriveStakingOutputInfo } from "../utils/staking";
 import { findMatchingTxOutputIndex } from "../utils/staking";
 import { isValidBabylonAddress } from "../utils/babylon";
 import { StakingError } from "../error";
 import { StakingErrorCode } from "../error";
+import { isNativeSegwit, isTaproot } from "../utils/btc";
 
 export interface BtcProvider {
   // Sign a PSBT
+  // Expecting the PSBT to be encoded in hex format.
   signPsbt(signingStep: SigningStep, psbtHex: string): Promise<string>;
-  // Sign a message using the ECDSA type
-  // This is optional and only required if you would like to use the 
-  // `createProofOfPossession` function
-  signMessage?: (signingStep: SigningStep, message: string, type: "ecdsa") => Promise<string>;
+  
+  // Signs a message using either ECDSA or BIP-322, depending on the address type.
+  // - Taproot and Native Segwit addresses will use BIP-322.
+  // - Legacy addresses will use ECDSA.
+  // Expecting the message to be encoded in base64 format.
+  signMessage: (
+    signingStep: SigningStep, message: string, type: "ecdsa" | "bip322-simple"
+  ) => Promise<string>;
 }
 
 export interface BabylonProvider {
+  /**
+   * Signs a Babylon chain transaction using the provided signing step.
+   * This is primarily used for signing MsgCreateBTCDelegation transactions
+   * which register the BTC delegation on the Babylon Genesis chain.
+   * 
+   * @param {SigningStep} signingStep - The current signing step context
+   * @param {object} msg - The Cosmos SDK transaction message to sign
+   * @param {string} msg.typeUrl - The Protobuf type URL identifying the message type
+   * @param {T} msg.value - The transaction message data matching the typeUrl
+   * @returns {Promise<Uint8Array>} The signed transaction bytes
+   */
   signTransaction: <T extends object>(
     signingStep: SigningStep,
     msg: {
@@ -106,7 +123,9 @@ export class BabylonBtcStakingManager {
    * @param babylonBtcTipHeight - The Babylon BTC tip height.
    * @param inputUTXOs - The UTXOs that will be used to pay for the staking
    * transaction.
-   * @param feeRate - The fee rate in satoshis per byte.
+   * @param feeRate - The fee rate in satoshis per byte. Typical value for the
+   * fee rate is above 1. If the fee rate is too low, the transaction will not
+   * be included in a block.
    * @param babylonAddress - The Babylon bech32 encoded address of the staker.
    * @returns The signed babylon pre-staking registration transaction in base64 
    * format.
@@ -182,7 +201,8 @@ export class BabylonBtcStakingManager {
    * @param stakingTxHeight - The BTC height in which the staking transaction 
    * is included.
    * @param stakingInput - The staking inputs.
-   * @param inclusionProof - The inclusion proof of the staking transaction.
+   * @param inclusionProof - Merkle Proof of Inclusion: Verifies transaction
+   * inclusion in a Bitcoin block that is k-deep.
    * @param babylonAddress - The Babylon bech32 encoded address of the staker.
    * @returns The signed babylon transaction in base64 format.
    */
@@ -249,7 +269,9 @@ export class BabylonBtcStakingManager {
    * @param stakingInput - The staking inputs.
    * @param inputUTXOs - The UTXOs that will be used to pay for the staking
    * transaction.
-   * @param feeRate - The fee rate in satoshis per byte.
+   * @param feeRate - The fee rate in satoshis per byte. Typical value for the
+   * fee rate is above 1. If the fee rate is too low, the transaction will not
+   * be included in a block.
    * @returns The estimated BTC fee in satoshis.
    */
   estimateBtcStakingFee(
@@ -462,7 +484,9 @@ export class BabylonBtcStakingManager {
    * @param stakingParamsVersion - The params version that was used to create the
    * delegation in Babylon chain
    * @param earlyUnbondingTx - The early unbonding transaction.
-   * @param feeRate - The fee rate in satoshis per byte.
+   * @param feeRate - The fee rate in satoshis per byte. Typical value for the
+   * fee rate is above 1. If the fee rate is too low, the transaction will not
+   * be included in a block.
    * @returns The signed withdrawal transaction and its fee.
    */
   async createSignedBtcWithdrawEarlyUnbondedTransaction(
@@ -509,7 +533,9 @@ export class BabylonBtcStakingManager {
    * @param stakingParamsVersion - The params version that was used to create the
    * delegation in Babylon chain
    * @param stakingTx - The staking transaction.
-   * @param feeRate - The fee rate in satoshis per byte.
+   * @param feeRate - The fee rate in satoshis per byte. Typical value for the
+   * fee rate is above 1. If the fee rate is too low, the transaction will not
+   * be included in a block.
    * @returns The signed withdrawal transaction and its fee.
    */
   async createSignedBtcWithdrawStakingExpiredTransaction(
@@ -556,7 +582,9 @@ export class BabylonBtcStakingManager {
    * @param stakingParamsVersion - The params version that was used to create the
    * delegation in Babylon chain
    * @param slashingTx - The slashing transaction.
-   * @param feeRate - The fee rate in satoshis per byte.
+   * @param feeRate - The fee rate in satoshis per byte. Typical value for the
+   * fee rate is above 1. If the fee rate is too low, the transaction will not
+   * be included in a block.
    * @returns The signed withdrawal transaction and its fee.
    */
   async createSignedBtcWithdrawSlashingTransaction(
@@ -601,22 +629,42 @@ export class BabylonBtcStakingManager {
    */
   async createProofOfPossession(
     bech32Address: string,
+    stakerBtcAddress: string,
   ): Promise<ProofOfPossessionBTC> {
-    if (!this.btcProvider.signMessage) {
-      throw new Error("Sign message function not found");
+    let sigType: BTCSigType = BTCSigType.ECDSA;
+
+    // For Taproot or Native SegWit addresses, use the BIP322 signature scheme
+    // in the proof of possession as it uses the same signature type as the regular
+    // input UTXO spend. For legacy addresses, use the ECDSA signature scheme.
+    if (
+      isTaproot(stakerBtcAddress, this.network) 
+        || isNativeSegwit(stakerBtcAddress, this.network)
+    ) {
+      sigType = BTCSigType.BIP322;
     }
-    // Create Proof of Possession
-    const bech32AddressHex = uint8ArrayToHex(fromBech32(bech32Address).data);
- 
+
     const signedBabylonAddress = await this.btcProvider.signMessage(
       SigningStep.PROOF_OF_POSSESSION,
-      bech32AddressHex,
-      "ecdsa",
+      bech32Address,
+      sigType === BTCSigType.BIP322 ? "bip322-simple" : "ecdsa",
     );
-    const ecdsaSig = Uint8Array.from(Buffer.from(signedBabylonAddress, "base64"));
+
+    let btcSig: Uint8Array;
+    if (sigType === BTCSigType.BIP322) {
+      const bip322Sig = BIP322Sig.fromPartial({
+        address: stakerBtcAddress,
+        sig: Buffer.from(signedBabylonAddress, "base64"),
+      });
+      // Encode the BIP322 protobuf message to a Uint8Array
+      btcSig = BIP322Sig.encode(bip322Sig).finish();
+    } else {
+      // Encode the ECDSA signature to a Uint8Array
+      btcSig = Buffer.from(signedBabylonAddress, "base64");
+    }
+
     return {
-      btcSigType: BTCSigType.ECDSA,
-      btcSig: ecdsaSig,
+      btcSigType: sigType,
+      btcSig
     };
   }
 
@@ -710,7 +758,10 @@ export class BabylonBtcStakingManager {
     }
 
     // Create proof of possession
-    const proofOfPossession = await this.createProofOfPossession(bech32Address);
+    const proofOfPossession = await this.createProofOfPossession(
+      bech32Address,
+      stakerBtcInfo.address,
+    );
 
     // Prepare the final protobuf message
     const msg: btcstakingtx.MsgCreateBTCDelegation =

modules/babylonlabs-io-btc-staking-ts/src/staking/stakingScript.ts

@@ -104,19 +104,19 @@ export class StakingScriptData {
     // check that the threshold is above 0 and less than or equal to
     // the size of the covenant emulators set
     if (
-      this.covenantThreshold == 0 ||
+      this.covenantThreshold <= 0 ||
       this.covenantThreshold > this.covenantKeys.length
     ) {
       return false;
     }
 
     // check that maximum value for staking time is not greater than uint16 and above 0
-    if (this.stakingTimeLock == 0 || this.stakingTimeLock > 65535) {
+    if (this.stakingTimeLock <= 0 || this.stakingTimeLock > 65535) {
       return false;
     }
 
     // check that maximum value for unbonding time is not greater than uint16 and above 0
-    if (this.unbondingTimeLock == 0 || this.unbondingTimeLock > 65535) {
+    if (this.unbondingTimeLock <= 0 || this.unbondingTimeLock > 65535) {
       return false;
     }
 

modules/babylonlabs-io-btc-staking-ts/src/staking/transactions.ts

@@ -1,4 +1,4 @@
-import { Psbt, Transaction, networks, payments, script, address } from "bitcoinjs-lib";
+import { Psbt, Transaction, networks, payments, script, address, opcodes } from "bitcoinjs-lib";
 import { Taptree } from "bitcoinjs-lib/src/types";
 
 import { BTC_DUST_SAT } from "../constants/dustSat";
@@ -15,6 +15,7 @@ import { REDEEM_VERSION } from "../constants/transaction";
 
 // https://bips.xyz/370
 const BTC_LOCKTIME_HEIGHT_TIME_CUTOFF = 500000000;
+const BTC_SLASHING_FRACTION_DIGITS = 4;
 
 /**
  * Constructs an unsigned BTC Staking transaction in psbt format.
@@ -537,7 +538,7 @@ function slashingTransaction(
     throw new Error("Slashing rate must be between 0 and 1");
   }
   // Round the slashing rate to two decimal places
-  slashingRate = parseFloat(slashingRate.toFixed(2));
+  slashingRate = parseFloat(slashingRate.toFixed(BTC_SLASHING_FRACTION_DIGITS));
   // Minimum fee must be a postive integer
   if (minimumFee <= 0 || !Number.isInteger(minimumFee)) {
     throw new Error("Minimum fee must be a positve integer");
@@ -574,9 +575,17 @@ function slashingTransaction(
   const stakingAmount = transaction.outs[outputIndex].value;
   // Slashing rate is a percentage of the staking amount, rounded down to
   // the nearest integer to avoid sending decimal satoshis
-  const slashingAmount = Math.floor(stakingAmount * slashingRate);
-  if (slashingAmount <= BTC_DUST_SAT) {
-    throw new Error("Slashing amount is less than dust limit");
+  const slashingAmount = Math.round(stakingAmount * slashingRate);
+
+  // Compute the slashing output
+  const slashingOutput = Buffer.from(slashingPkScriptHex, "hex");
+
+  // If OP_RETURN is not included, the slashing amount must be greater than the
+  // dust limit.
+  if (opcodes.OP_RETURN != slashingOutput[0]) {
+    if (slashingAmount <= BTC_DUST_SAT) {
+      throw new Error("Slashing amount is less than dust limit");
+    }  
   }
 
   const userFunds = stakingAmount - slashingAmount - minimumFee;
@@ -602,7 +611,7 @@ function slashingTransaction(
 
   // Add the slashing output
   psbt.addOutput({
-    script: Buffer.from(slashingPkScriptHex, "hex"),
+    script: slashingOutput,
     value: slashingAmount,
   });
 

modules/babylonlabs-io-btc-staking-ts/src/utils/btc.ts

@@ -32,22 +32,60 @@ export const isValidBitcoinAddress = (
  * @param {object} network - The Bitcoin network (e.g., bitcoin.networks.bitcoin).
  * @returns {boolean} - True if the address is a Taproot address, otherwise false.
  */
-export const isTaproot = (taprootAddress: string, network: networks.Network): boolean => {
+export const isTaproot = (
+  taprootAddress: string,
+  network: networks.Network,
+): boolean => {
   try {
     const decoded = address.fromBech32(taprootAddress);
     if (decoded.version !== 1) {
       return false;
     }
-    switch (network) {
-      case networks.bitcoin:
-        // Check if address statrts with "bc1p"
-        return taprootAddress.startsWith("bc1p");
-      case networks.testnet:
-        // signet, regtest and testnet taproot addresses start with "tb1p" or "sb1p"
-        return taprootAddress.startsWith("tb1p") || taprootAddress.startsWith("sb1p");
-      default:
-        return false;
-    }  
+
+    // Compare network properties instead of object reference
+    // The bech32 is hardcoded in the bitcoinjs-lib library.
+    // https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/ts_src/networks.ts#L36
+    if (network.bech32 === networks.bitcoin.bech32) {
+      // Check if address starts with "bc1p"
+      return taprootAddress.startsWith("bc1p");
+    } else if (network.bech32 === networks.testnet.bech32) {
+      // signet, regtest and testnet taproot addresses start with "tb1p" or "sb1p"
+      return taprootAddress.startsWith("tb1p") || taprootAddress.startsWith("sb1p");
+    }
+    return false;
+  } catch (error) {
+    return false;
+  }
+};
+
+/**
+ * Check whether the given address is a Native SegWit address.
+ *
+ * @param {string} segwitAddress - The Bitcoin bech32 encoded address to check.
+ * @param {object} network - The Bitcoin network (e.g., bitcoin.networks.bitcoin).
+ * @returns {boolean} - True if the address is a Native SegWit address, otherwise false.
+ */
+export const isNativeSegwit = (
+  segwitAddress: string,
+  network: networks.Network,
+): boolean => {
+  try {
+    const decoded = address.fromBech32(segwitAddress);
+    if (decoded.version !== 0) {
+      return false;
+    }
+    
+    // Compare network properties instead of object reference
+    // The bech32 is hardcoded in the bitcoinjs-lib library.
+    // https://github.com/bitcoinjs/bitcoinjs-lib/blob/master/ts_src/networks.ts#L36
+    if (network.bech32 === networks.bitcoin.bech32) {
+      // Check if address starts with "bc1q"
+      return segwitAddress.startsWith("bc1q");
+    } else if (network.bech32 === networks.testnet.bech32) {
+      // testnet native segwit addresses start with "tb1q"
+      return segwitAddress.startsWith("tb1q");
+    }
+    return false;
   } catch (error) {
     return false;
   }

modules/utxo-staking/package.json

@@ -43,11 +43,12 @@
   },
   "dependencies": {
     "@babylonlabs-io/babylon-proto-ts": "1.0.0",
-    "@bitgo/babylonlabs-io-btc-staking-ts": "^0.5.0",
+    "@bitgo/babylonlabs-io-btc-staking-ts": "^1.0.0",
     "@bitgo/unspents": "^0.47.21",
     "@bitgo/utxo-core": "^1.8.0",
     "@bitgo/utxo-lib": "^11.3.0",
     "@bitgo/wasm-miniscript": "2.0.0-beta.7",
+    "bip322-js": "^2.0.0",
     "bitcoinjs-lib": "^6.1.7",
     "fp-ts": "^2.16.2",
     "io-ts": "npm:@bitgo-forks/[email protected]",

modules/utxo-staking/scripts/babylon-params.ts

@@ -5,7 +5,7 @@ import { hideBin } from 'yargs/helpers';
 
 function getBaseUrl(network: 'mainnet' | 'testnet') {
   if (network === 'mainnet') {
-    throw new Error('Mainnet not supported');
+    return 'https://babylon.nodes.guru/api';
   }
   return 'https://babylon-testnet-api.nodes.guru';
 }
@@ -16,7 +16,7 @@ async function getParams(network: BabylonNetwork, version: number): Promise<unkn
   const url = `${getBaseUrl(network)}/babylon/btcstaking/v1/params/${version}`;
   const resp = await fetch(url);
   if (!resp.ok) {
-    throw new Error(`Failed to fetch ${url}: ${resp.statusText}`);
+    throw new Error(`Failed to fetch ${url}: ${resp.status} ${resp.statusText}`);
   }
   return await resp.json();
 }