feat(babylonlabs-io-btc-staking-ts): backport changes from v1.0.3

Add BIP-322 signature support for Taproot and Native SegWit addresses in
the proof of possession generation. Previously only ECDSA signatures were
supported for legacy addresses.

Improves API documentation to better explain function parameters and
required BTC fee rates. Fixes zero equality checks to handle negative
values correctly.

BTC-2032

Co-authored-by: llm-git <[email protected]>

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;
   }