@bitgo-beta/babylonlabs-io-btc-staking-ts 0.4.0-beta.515 → 0.4.0-beta.517

package/dist/index.d.cts

@@ -202,6 +202,49 @@ export declare class Staking {
 	 * @throws {StakingError} - If the transaction cannot be built
 	 */
 	createStakingTransaction(stakingAmountSat: number, inputUTXOs: UTXO[], feeRate: number): TransactionResult;
+	/**
+	 * Creates a staking expansion transaction that extends an existing BTC stake
+	 * to new finality providers or renews the timelock.
+	 *
+	 * This method implements RFC 037 BTC Stake Expansion,
+	 * allowing existing active BTC staking transactions
+	 * to extend their delegation to new finality providers without going through
+	 * the full unbonding process.
+	 *
+	 * The expansion transaction:
+	 * 1. Spends the previous staking transaction output as the first input
+	 * 2. Uses funding UTXO as additional input to cover transaction fees or
+	 *    to increase the staking amount
+	 * 3. Creates a new staking output with expanded finality provider coverage or
+	 *    renews the timelock
+	 * 4. Has an output returning the remaining funds as change (if any) to the
+	 * staker BTC address
+	 *
+	 * @param {number} stakingAmountSat - The total staking amount in satoshis
+	 * (The amount had to be equal to the previous staking amount for now, this
+	 * lib does not yet support increasing the staking amount at this stage)
+	 * @param {UTXO[]} inputUTXOs - Available UTXOs to use for funding the
+	 * expansion transaction fees. Only one will be selected for the expansion
+	 * @param {number} feeRate - Fee rate in satoshis per byte for the
+	 * expansion transaction
+	 * @param {StakingParams} paramsForPreviousStakingTx - Staking parameters
+	 * used in the previous staking transaction
+	 * @param {Object} previousStakingTxInfo - Necessary information to spend the
+	 * previous staking transaction.
+	 * @returns {TransactionResult & { fundingUTXO: UTXO }} - An object containing
+	 * the unsigned expansion transaction and calculated fee, and the funding UTXO
+	 * @throws {StakingError} - If the transaction cannot be built or validation
+	 * fails
+	 */
+	createStakingExpansionTransaction(stakingAmountSat: number, inputUTXOs: UTXO[], feeRate: number, paramsForPreviousStakingTx: StakingParams, previousStakingTxInfo: {
+		stakingTx: Transaction;
+		stakingInput: {
+			finalityProviderPksNoCoordHex: string[];
+			stakingTimelock: number;
+		};
+	}): TransactionResult & {
+		fundingUTXO: UTXO;
+	};
 	/**
 	 * Create a staking psbt based on the existing staking transaction.
 	 *
@@ -212,6 +255,28 @@ export declare class Staking {
 	 * @returns {Psbt} - The psbt.
 	 */
 	toStakingPsbt(stakingTx: Transaction, inputUTXOs: UTXO[]): Psbt;
+	/**
+	 * Convert a staking expansion transaction to a PSBT.
+	 *
+	 * @param {Transaction} stakingExpansionTx - The staking expansion
+	 * transaction to convert
+	 * @param {UTXO[]} inputUTXOs - Available UTXOs for the
+	 * funding input (second input)
+	 * @param {StakingParams} paramsForPreviousStakingTx - Staking parameters
+	 * used for the previous staking transaction
+	 * @param {Object} previousStakingTxInfo - Information about the previous
+	 * staking transaction
+	 * @returns {Psbt} The PSBT for the staking expansion transaction
+	 * @throws {Error} If the previous staking output cannot be found or
+	 * validation fails
+	 */
+	toStakingExpansionPsbt(stakingExpansionTx: Transaction, inputUTXOs: UTXO[], paramsForPreviousStakingTx: StakingParams, previousStakingTxInfo: {
+		stakingTx: Transaction;
+		stakingInput: {
+			finalityProviderPksNoCoordHex: string[];
+			stakingTimelock: number;
+		};
+	}): Psbt;
 	/**
 	 * Create an unbonding transaction for staking.
 	 *
@@ -291,6 +356,7 @@ export interface ManagerEvents {
 	"delegation:stake": (data?: EventData) => void;
 	"delegation:unbond": (data?: EventData) => void;
 	"delegation:withdraw": (data?: EventData) => void;
+	"delegation:expand": (data?: EventData) => void;
 }
 export type DelegationEvent = keyof ManagerEvents;
 export interface Action {
@@ -322,6 +388,7 @@ export interface SignPsbtOptions {
 export interface BtcProvider {
 	signPsbt(psbtHex: string, options?: SignPsbtOptions): Promise<string>;
 	signMessage: (message: string, type: "ecdsa" | "bip322-simple") => Promise<string>;
+	getTransactionHex(txid: string): Promise<string>;
 }
 export interface BabylonProvider {
 	/**
@@ -338,6 +405,18 @@ export interface BabylonProvider {
 		typeUrl: string;
 		value: T;
 	}) => Promise<Uint8Array>;
+	/**
+	 * Gets the current height of the Babylon Genesis chain.
+	 *
+	 * @returns {Promise<number>} The current Babylon chain height
+	 */
+	getCurrentHeight?: () => Promise<number>;
+	/**
+	 * Gets the chain ID of the Babylon Genesis chain.
+	 *
+	 * @returns {Promise<string>} The Babylon chain ID
+	 */
+	getChainId?: () => Promise<string>;
 }
 export interface StakingInputs {
 	finalityProviderPksNoCoordHex: string[];
@@ -349,13 +428,40 @@ export interface InclusionProof {
 	merkle: string[];
 	blockHashHex: string;
 }
+/**
+ * Upgrade configuration for Babylon POP (Proof of Possession) context.
+ * This is used to determine when to switch to the new POP context format
+ * based on the Babylon chain height and version.
+ */
+export interface UpgradeConfig {
+	/**
+	 * POP context upgrade configuration.
+	 */
+	pop?: PopUpgradeConfig;
+}
+/**
+ * Configuration for POP context upgrade.
+ * - upgradeHeight: The Babylon chain height at which the POP context upgrade is activated.
+ * - version: The version of the POP context to use after the upgrade.
+ */
+export interface PopUpgradeConfig {
+	/**
+	 * The Babylon chain height at which the POP context upgrade is activated.
+	 */
+	upgradeHeight: number;
+	/**
+	 * The version of the POP context to use after the upgrade.
+	 */
+	version: number;
+}
 export declare class BabylonBtcStakingManager {
 	protected network: networks.Network;
 	protected stakingParams: VersionedStakingParams[];
 	protected btcProvider: BtcProvider;
 	protected babylonProvider: BabylonProvider;
 	protected ee?: Emitter<ManagerEvents> | undefined;
-	constructor(network: networks.Network, stakingParams: VersionedStakingParams[], btcProvider: BtcProvider, babylonProvider: BabylonProvider, ee?: Emitter<ManagerEvents> | undefined);
+	private upgradeConfig?;
+	constructor(network: networks.Network, stakingParams: VersionedStakingParams[], btcProvider: BtcProvider, babylonProvider: BabylonProvider, ee?: Emitter<ManagerEvents> | undefined, upgradeConfig?: UpgradeConfig);
 	/**
 	 * Creates a signed Pre-Staking Registration transaction that is ready to be
 	 * sent to the Babylon chain.
@@ -376,6 +482,41 @@ export declare class BabylonBtcStakingManager {
 		signedBabylonTx: Uint8Array;
 		stakingTx: Transaction;
 	}>;
+	/**
+	 * Create a signed staking expansion transaction that is ready to be sent to
+	 * the Babylon chain.
+	 */
+	stakingExpansionRegistrationBabylonTransaction(stakerBtcInfo: StakerInfo, stakingInput: StakingInputs, babylonBtcTipHeight: number, inputUTXOs: UTXO[], feeRate: number, babylonAddress: string, previousStakingTxInfo: {
+		stakingTx: Transaction;
+		paramVersion: number;
+		stakingInput: StakingInputs;
+	}): Promise<{
+		signedBabylonTx: Uint8Array;
+		stakingTx: Transaction;
+	}>;
+	/**
+	 * Estimates the transaction fee for a BTC staking expansion transaction.
+	 *
+	 * @param {StakerInfo} stakerBtcInfo - The staker's Bitcoin information
+	 * including address and public key
+	 * @param {number} babylonBtcTipHeight - The current Babylon BTC tip height
+	 * used to determine staking parameters
+	 * @param {StakingInputs} stakingInput - The new staking input parameters for
+	 * the expansion
+	 * @param {UTXO[]} inputUTXOs - Available UTXOs that can be used for funding
+	 * the expansion transaction
+	 * @param {number} feeRate - Fee rate in satoshis per byte for the expansion
+	 * transaction
+	 * @param {Object} previousStakingTxInfo - Information about the previous
+	 * staking transaction being expanded
+	 * @returns {number} - The estimated transaction fee in satoshis
+	 * @throws {Error} - If validation fails or the fee cannot be calculated
+	 */
+	estimateBtcStakingExpansionFee(stakerBtcInfo: StakerInfo, babylonBtcTipHeight: number, stakingInput: StakingInputs, inputUTXOs: UTXO[], feeRate: number, previousStakingTxInfo: {
+		stakingTx: Transaction;
+		paramVersion: number;
+		stakingInput: StakingInputs;
+	}): number;
 	/**
 	 * Creates a signed post-staking registration transaction that is ready to be
 	 * sent to the Babylon chain. This is used when a staking transaction is
@@ -424,6 +565,35 @@ export declare class BabylonBtcStakingManager {
 	 * @returns The signed staking transaction.
 	 */
 	createSignedBtcStakingTransaction(stakerBtcInfo: StakerInfo, stakingInput: StakingInputs, unsignedStakingTx: Transaction, inputUTXOs: UTXO[], stakingParamsVersion: number): Promise<Transaction>;
+	/**
+	 * Creates a signed staking expansion transaction that is ready to be sent to
+	 * the BTC network.
+	 *
+	 * @param {StakerInfo} stakerBtcInfo - The staker's BTC information including
+	 * address and public key
+	 * @param {StakingInputs} stakingInput - The staking inputs for the expansion
+	 * @param {Transaction} unsignedStakingExpansionTx - The unsigned staking
+	 * expansion transaction
+	 * @param {UTXO[]} inputUTXOs - Available UTXOs for the funding input
+	 * @param {number} stakingParamsVersion - The version of staking parameters
+	 * that was used when registering the staking expansion delegation.
+	 * @param {Object} previousStakingTxInfo - Information about the previous
+	 * staking transaction
+	 * @param {Array} covenantStakingExpansionSignatures - Covenant committee
+	 * signatures for the expansion
+	 * @returns {Promise<Transaction>} The fully signed staking expansion
+	 * transaction
+	 * @throws {Error} If signing fails, validation fails, or required data is
+	 * missing
+	 */
+	createSignedBtcStakingExpansionTransaction(stakerBtcInfo: StakerInfo, stakingInput: StakingInputs, unsignedStakingExpansionTx: Transaction, inputUTXOs: UTXO[], stakingParamsVersion: number, previousStakingTxInfo: {
+		stakingTx: Transaction;
+		paramVersion: number;
+		stakingInput: StakingInputs;
+	}, covenantStakingExpansionSignatures: {
+		btcPkHex: string;
+		sigHex: string;
+	}[]): Promise<Transaction>;
 	/**
 	 * Creates a partial signed unbonding transaction that is only signed by the
 	 * staker. In order to complete the unbonding transaction, the covenant
@@ -505,7 +675,7 @@ export declare class BabylonBtcStakingManager {
 	 * @param bech32Address - The staker's bech32 address.
 	 * @returns The proof of possession.
 	 */
-	createProofOfPossession(channel: "delegation:create" | "delegation:register", bech32Address: string, stakerBtcAddress: string): Promise<ProofOfPossessionBTC>;
+	createProofOfPossession(channel: "delegation:create" | "delegation:register" | "delegation:expand", bech32Address: string, stakerBtcAddress: string): Promise<ProofOfPossessionBTC>;
 	/**
 	 * Creates the unbonding, slashing, and unbonding slashing transactions and
 	 * PSBTs.
@@ -525,12 +695,22 @@ export declare class BabylonBtcStakingManager {
 	 * @param stakerBtcInfo - The staker's BTC information such as address and
 	 * public key
 	 * @param params - The staking parameters.
-	 * @param inclusionProof - The inclusion proof of the staking transaction.
+	 * @param options - The options for the BTC delegation.
+	 * @param options.inclusionProof - The inclusion proof of the staking
+	 * transaction.
+	 * @param options.delegationExpansionInfo - The information for the BTC
+	 * delegation expansion.
 	 * @returns The protobuf message.
 	 */
-	createBtcDelegationMsg(channel: "delegation:create" | "delegation:register", stakingInstance: Staking, stakingInput: StakingInputs, stakingTx: Transaction, bech32Address: string, stakerBtcInfo: StakerInfo, params: StakingParams, inclusionProof?: btcstaking.InclusionProof): Promise<{
+	createBtcDelegationMsg(channel: "delegation:create" | "delegation:register" | "delegation:expand", stakingInstance: Staking, stakingInput: StakingInputs, stakingTx: Transaction, bech32Address: string, stakerBtcInfo: StakerInfo, params: StakingParams, options?: {
+		inclusionProof?: btcstaking.InclusionProof;
+		delegationExpansionInfo?: {
+			previousStakingTx: Transaction;
+			fundingTx: Transaction;
+		};
+	}): Promise<{
 		typeUrl: string;
-		value: btcstakingtx.MsgCreateBTCDelegation;
+		value: btcstakingtx.MsgCreateBTCDelegation | btcstakingtx.MsgBtcStakeExpand;
 	}>;
 	/**
 	 * Gets the inclusion proof for the staking transaction.
@@ -662,6 +842,42 @@ export declare function stakingTransaction(scripts: {
 	slashingScript: Buffer;
 	dataEmbedScript?: Buffer;
 }, amount: number, changeAddress: string, inputUTXOs: UTXO[], network: networks.Network, feeRate: number, lockHeight?: number): TransactionResult;
+/**
+ * Expand an existing staking transaction with additional finality providers
+ * or renew timelock.
+ *
+ * This function builds a Bitcoin transaction that:
+ * 1. Spends the previous staking transaction output as the first input
+ * 2. Uses a funding UTXO as the second input to cover transaction fees
+ * 3. Creates new staking outputs where the timelock is renewed or FPs added
+ * 4. Returns any remaining funds as change
+ *
+ * @param network - Bitcoin network (mainnet, testnet, etc.)
+ * @param scripts - Scripts for the new staking outputs
+ * @param amount - Total staking amount (must equal previous staking amount,
+ * we only support equal amounts for now)
+ * @param changeAddress - Bitcoin address to receive change from funding UTXO
+ * @param feeRate - Fee rate in satoshis per byte
+ * @param inputUTXOs - Available UTXOs to use for funding the expansion
+ * @param previousStakingTxInfo - Details of the previous staking transaction
+ * being expanded
+ * @returns {TransactionResult & { fundingUTXO: UTXO }} containing the built
+ * transaction and calculated fee, and the funding UTXO
+ */
+export declare function stakingExpansionTransaction(network: networks.Network, scripts: {
+	timelockScript: Buffer;
+	unbondingScript: Buffer;
+	slashingScript: Buffer;
+}, amount: number, changeAddress: string, feeRate: number, inputUTXOs: UTXO[], previousStakingTxInfo: {
+	stakingTx: Transaction;
+	scripts: {
+		timelockScript: Buffer;
+		unbondingScript: Buffer;
+		slashingScript: Buffer;
+	};
+}): TransactionResult & {
+	fundingUTXO: UTXO;
+};
 /**
  * Constructs a withdrawal transaction for manually unbonded delegation.
  *
@@ -980,39 +1196,40 @@ export declare const deriveSlashingOutput: (scripts: {
  */
 export declare const findMatchingTxOutputIndex: (tx: Transaction, outputAddress: string, network: networks.Network) => number;
 /**
- * Validate the staking transaction input data.
+ * toBuffers converts an array of strings to an array of buffers.
  *
- * @param {number} stakingAmountSat - The staking amount in satoshis.
- * @param {number} timelock - The staking time in blocks.
- * @param {StakingParams} params - The staking parameters.
- * @param {UTXO[]} inputUTXOs - The input UTXOs.
- * @param {number} feeRate - The Bitcoin fee rate in sat/vbyte
- * @throws {StakingError} - If the input data is invalid.
+ * @param {string[]} inputs - The input strings.
+ * @returns {Buffer[]} - The buffers.
+ * @throws {StakingError} - If the values cannot be converted to buffers.
  */
-export declare const validateStakingTxInputData: (stakingAmountSat: number, timelock: number, params: StakingParams, inputUTXOs: UTXO[], feeRate: number) => void;
+export declare const toBuffers: (inputs: string[]) => Buffer[];
 /**
- * Validate the staking parameters.
- * Extend this method to add additional validation for staking parameters based
- * on the staking type.
- * @param {StakingParams} params - The staking parameters.
- * @throws {StakingError} - If the parameters are invalid.
+ * Strips all signatures from a transaction by clearing both the script and
+ * witness data. This is due to the fact that we only need the raw unsigned
+ * transaction structure. The signatures are sent in a separate protobuf field
+ * when creating the delegation message in the Babylon.
+ * @param tx - The transaction to strip signatures from
+ * @returns A copy of the transaction with all signatures removed
  */
-export declare const validateParams: (params: StakingParams) => void;
+export declare const clearTxSignatures: (tx: Transaction) => Transaction;
 /**
- * Validate the staking timelock.
- *
- * @param {number} stakingTimelock - The staking timelock.
- * @param {StakingParams} params - The staking parameters.
- * @throws {StakingError} - If the staking timelock is invalid.
+ * Derives the merkle proof from the list of hex strings. Note the
+ * sibling hashes are reversed from hex before concatenation.
+ * @param merkle - The merkle proof hex strings.
+ * @returns The merkle proof in hex string format.
  */
-export declare const validateStakingTimelock: (stakingTimelock: number, params: StakingParams) => void;
+export declare const deriveMerkleProof: (merkle: string[]) => string;
 /**
- * toBuffers converts an array of strings to an array of buffers.
+ * Extracts the first valid Schnorr signature from a signed transaction.
  *
- * @param {string[]} inputs - The input strings.
- * @returns {Buffer[]} - The buffers.
- * @throws {StakingError} - If the values cannot be converted to buffers.
+ * Since we only handle transactions with a single input and request a signature
+ * for one public key, there can be at most one signature from the Bitcoin node.
+ * A valid Schnorr signature is exactly 64 bytes in length.
+ *
+ * @param singedTransaction - The signed Bitcoin transaction to extract the signature from
+ * @returns The first valid 64-byte Schnorr signature found in the transaction witness data,
+ *          or undefined if no valid signature exists
  */
-export declare const toBuffers: (inputs: string[]) => Buffer[];
+export declare const extractFirstSchnorrSignatureFromTransaction: (singedTransaction: Transaction) => Buffer | undefined;
 
 export {};