UNPKG

@bitgo/babylonlabs-io-btc-staking-ts

Version:

Library exposing methods for the creation and consumption of Bitcoin transactions pertaining to Babylon's Bitcoin Staking protocol.

1,084 lines (1,081 loc) 56.2 kB
// Generated by dts-bundle-generator v9.5.1 import { btcstaking, btcstakingtx } from '@babylonlabs-io/babylon-proto-ts'; import { ProofOfPossessionBTC } from '@babylonlabs-io/babylon-proto-ts/dist/generated/babylon/btcstaking/v1/pop'; import { PsbtInputExtended } from 'bip174/src/lib/interfaces'; import { Psbt, Transaction, networks } from 'bitcoinjs-lib'; import { Input } from 'bitcoinjs-lib/src/transaction'; import { Emitter } from 'nanoevents'; /** * Base interface for staking parameters that define the rules and constraints * for staking operations. */ export interface StakingParams { covenantNoCoordPks: string[]; covenantQuorum: number; unbondingTime: number; unbondingFeeSat: number; maxStakingAmountSat: number; minStakingAmountSat: number; maxStakingTimeBlocks: number; minStakingTimeBlocks: number; slashing?: { slashingPkScriptHex: string; slashingRate: number; minSlashingTxFeeSat: number; }; } /** * Type for StakingParams where slashing is required */ export type StakingParamsWithSlashing = StakingParams & { slashing: NonNullable<StakingParams["slashing"]>; }; /** * Type guard to check if slashing exists in StakingParams */ export declare function hasSlashing(params: StakingParams): params is StakingParams & { slashing: NonNullable<StakingParams["slashing"]>; }; /** * Extension of StakingParams that includes activation height and version information. * These parameters are used to identify and select the appropriate staking rules at * different blockchain heights, but do not affect the actual staking transaction content. */ export interface VersionedStakingParams extends StakingParams { btcActivationHeight: number; version: number; } /** * Extension of VersionedStakingParams that includes a tag field for observability. */ export interface ObservableVersionedStakingParams extends VersionedStakingParams { tag: string; } /** * PsbtResult is an object containing a partially signed transaction and its fee */ export interface PsbtResult { psbt: Psbt; fee: number; } /** * TransactionResult is an object containing an unsigned transaction and its fee */ export interface TransactionResult { transaction: Transaction; fee: number; } export interface UTXO { txid: string; vout: number; value: number; scriptPubKey: string; rawTxHex?: string; redeemScript?: string; witnessScript?: string; } export interface StakingScripts { timelockScript: Buffer; unbondingScript: Buffer; slashingScript: Buffer; unbondingTimelockScript: Buffer; } export declare class StakingScriptData { stakerKey: Buffer; finalityProviderKeys: Buffer[]; covenantKeys: Buffer[]; covenantThreshold: number; stakingTimeLock: number; unbondingTimeLock: number; constructor(stakerKey: Buffer, finalityProviderKeys: Buffer[], covenantKeys: Buffer[], covenantThreshold: number, stakingTimelock: number, unbondingTimelock: number); /** * Validates the staking script. * @returns {boolean} Returns true if the staking script is valid, otherwise false. */ validate(): boolean; /** * Builds a timelock script. * @param timelock - The timelock value to encode in the script. * @returns {Buffer} containing the compiled timelock script. */ buildTimelockScript(timelock: number): Buffer; /** * Builds the staking timelock script. * Only holder of private key for given pubKey can spend after relative lock time * Creates the timelock script in the form: * <stakerPubKey> * OP_CHECKSIGVERIFY * <stakingTimeBlocks> * OP_CHECKSEQUENCEVERIFY * @returns {Buffer} The staking timelock script. */ buildStakingTimelockScript(): Buffer; /** * Builds the unbonding timelock script. * Creates the unbonding timelock script in the form: * <stakerPubKey> * OP_CHECKSIGVERIFY * <unbondingTimeBlocks> * OP_CHECKSEQUENCEVERIFY * @returns {Buffer} The unbonding timelock script. */ buildUnbondingTimelockScript(): Buffer; /** * Builds the unbonding script in the form: * buildSingleKeyScript(stakerPk, true) || * buildMultiKeyScript(covenantPks, covenantThreshold, false) * || means combining the scripts * @returns {Buffer} The unbonding script. */ buildUnbondingScript(): Buffer; /** * Builds the slashing script for staking in the form: * buildSingleKeyScript(stakerPk, true) || * buildMultiKeyScript(finalityProviderPKs, 1, true) || * buildMultiKeyScript(covenantPks, covenantThreshold, false) * || means combining the scripts * The slashing script is a combination of single-key and multi-key scripts. * The single-key script is used for staker key verification. * The multi-key script is used for finality provider key verification and covenant key verification. * @returns {Buffer} The slashing script as a Buffer. */ buildSlashingScript(): Buffer; /** * Builds the staking scripts. * @returns {StakingScripts} The staking scripts. */ buildScripts(): StakingScripts; /** * Builds a single key script in the form: * buildSingleKeyScript creates a single key script * <pk> OP_CHECKSIGVERIFY (if withVerify is true) * <pk> OP_CHECKSIG (if withVerify is false) * @param pk - The public key buffer. * @param withVerify - A boolean indicating whether to include the OP_CHECKSIGVERIFY opcode. * @returns The compiled script buffer. */ buildSingleKeyScript(pk: Buffer, withVerify: boolean): Buffer; /** * Builds a multi-key script in the form: * <pk1> OP_CHEKCSIG <pk2> OP_CHECKSIGADD <pk3> OP_CHECKSIGADD ... <pkN> OP_CHECKSIGADD <threshold> OP_NUMEQUAL * <withVerify -> OP_NUMEQUALVERIFY> * It validates whether provided keys are unique and the threshold is not greater than number of keys * If there is only one key provided it will return single key sig script * @param pks - An array of public keys. * @param threshold - The required number of valid signers. * @param withVerify - A boolean indicating whether to include the OP_VERIFY opcode. * @returns The compiled multi-key script as a Buffer. * @throws {Error} If no keys are provided, if the required number of valid signers is greater than the number of provided keys, or if duplicate keys are provided. */ buildMultiKeyScript(pks: Buffer[], threshold: number, withVerify: boolean): Buffer; } export interface StakerInfo { address: string; publicKeyNoCoordHex: string; } export declare class Staking { network: networks.Network; stakerInfo: StakerInfo; params: StakingParams; finalityProviderPksNoCoordHex: string[]; stakingTimelock: number; constructor(network: networks.Network, stakerInfo: StakerInfo, params: StakingParams, finalityProviderPksNoCoordHex: string[], stakingTimelock: number); /** * buildScripts builds the staking scripts for the staking transaction. * Note: different staking types may have different scripts. * e.g the observable staking script has a data embed script. * * @returns {StakingScripts} - The staking scripts. */ buildScripts(): StakingScripts; /** * Create a staking transaction for staking. * * @param {number} stakingAmountSat - The amount to stake in satoshis. * @param {UTXO[]} inputUTXOs - The UTXOs to use as inputs for the staking * transaction. * @param {number} feeRate - The fee rate for the transaction in satoshis per byte. * @returns {TransactionResult} - An object containing the unsigned * transaction, and fee * @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. * * @param {Transaction} stakingTx - The staking transaction. * @param {UTXO[]} inputUTXOs - The UTXOs to use as inputs for the staking * transaction. The UTXOs that were used to create the staking transaction should * be included in this array. * @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. * * @param {Transaction} stakingTx - The staking transaction to unbond. * @returns {TransactionResult} - An object containing the unsigned * transaction, and fee * @throws {StakingError} - If the transaction cannot be built */ createUnbondingTransaction(stakingTx: Transaction): TransactionResult; /** * Create an unbonding psbt based on the existing unbonding transaction and * staking transaction. * * @param {Transaction} unbondingTx - The unbonding transaction. * @param {Transaction} stakingTx - The staking transaction. * * @returns {Psbt} - The psbt. */ toUnbondingPsbt(unbondingTx: Transaction, stakingTx: Transaction): Psbt; /** * Creates a withdrawal transaction that spends from an unbonding or slashing * transaction. The timelock on the input transaction must have expired before * this withdrawal can be valid. * * @param {Transaction} earlyUnbondedTx - The unbonding or slashing * transaction to withdraw from * @param {number} feeRate - Fee rate in satoshis per byte for the withdrawal * transaction * @returns {PsbtResult} - Contains the unsigned PSBT and fee amount * @throws {StakingError} - If the input transaction is invalid or withdrawal * transaction cannot be built */ createWithdrawEarlyUnbondedTransaction(earlyUnbondedTx: Transaction, feeRate: number): PsbtResult; /** * Create a withdrawal psbt that spends a naturally expired staking * transaction. * * @param {Transaction} stakingTx - The staking transaction to withdraw from. * @param {number} feeRate - The fee rate for the transaction in satoshis per byte. * @returns {PsbtResult} - An object containing the unsigned psbt and fee * @throws {StakingError} - If the delegation is invalid or the transaction cannot be built */ createWithdrawStakingExpiredPsbt(stakingTx: Transaction, feeRate: number): PsbtResult; /** * Create a slashing psbt spending from the staking output. * * @param {Transaction} stakingTx - The staking transaction to slash. * @returns {PsbtResult} - An object containing the unsigned psbt and fee * @throws {StakingError} - If the delegation is invalid or the transaction cannot be built */ createStakingOutputSlashingPsbt(stakingTx: Transaction): PsbtResult; /** * Create a slashing psbt for an unbonding output. * * @param {Transaction} unbondingTx - The unbonding transaction to slash. * @returns {PsbtResult} - An object containing the unsigned psbt and fee * @throws {StakingError} - If the delegation is invalid or the transaction cannot be built */ createUnbondingOutputSlashingPsbt(unbondingTx: Transaction): PsbtResult; /** * Create a withdraw slashing psbt that spends a slashing transaction from the * staking output. * * @param {Transaction} slashingTx - The slashing transaction. * @param {number} feeRate - The fee rate for the transaction in satoshis per byte. * @returns {PsbtResult} - An object containing the unsigned psbt and fee * @throws {StakingError} - If the delegation is invalid or the transaction cannot be built */ createWithdrawSlashingPsbt(slashingTx: Transaction, feeRate: number): PsbtResult; } export type RegistrationStep = "staking-slashing" | "unbonding-slashing" | "proof-of-possession" | "create-btc-delegation-msg"; export type WithdrawalType = "staking-expired" | "early-unbonded" | "slashing"; export type EventData = Record<string, string | number | string[] | number[]>; export interface ManagerEvents { "delegation:create": (data?: EventData) => void; "delegation:register": (data?: EventData) => void; "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 { name: ActionName; } declare enum ActionName { SIGN_BTC_STAKING_TRANSACTION = "sign-btc-staking-transaction", SIGN_BTC_UNBONDING_TRANSACTION = "sign-btc-unbonding-transaction", SIGN_BTC_WITHDRAW_TRANSACTION = "sign-btc-withdraw-transaction", SIGN_BTC_SLASHING_TRANSACTION = "sign-btc-slashing-transaction", SIGN_BTC_UNBONDING_SLASHING_TRANSACTION = "sign-btc-unbonding-slashing-transaction" } export interface Contract { id: ContractId; params: ContractData; } declare enum ContractId { STAKING = "babylon:staking", UNBONDING = "babylon:unbonding", SLASHING = "babylon:slashing", WITHDRAW = "babylon:withdraw", SLASHING_BURN = "babylon:slashing-burn" } export type ContractData = Record<string, string | number | string[] | number[]>; export interface SignPsbtOptions { contracts: Contract[]; action: Action; } 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 { /** * Signs a Babylon chain transaction. * This is primarily used for signing MsgCreateBTCDelegation transactions * which register the BTC delegation on the Babylon Genesis chain. * * @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>(msg: { 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[]; stakingAmountSat: number; stakingTimelock: number; } export interface InclusionProof { pos: number; 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; 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. * @param stakerBtcInfo - The staker BTC info which includes the BTC address * and the no-coord public key in hex format. * @param stakingInput - The staking inputs. * @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. 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. */ preStakeRegistrationBabylonTransaction(stakerBtcInfo: StakerInfo, stakingInput: StakingInputs, babylonBtcTipHeight: number, inputUTXOs: UTXO[], feeRate: number, babylonAddress: string): Promise<{ 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 * already created and included in a BTC block and we want to register it on * the Babylon chain. * @param stakerBtcInfo - The staker BTC info which includes the BTC address * and the no-coord public key in hex format. * @param stakingTx - The staking transaction. * @param stakingTxHeight - The BTC height in which the staking transaction * is included. * @param stakingInput - The staking inputs. * @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. */ postStakeRegistrationBabylonTransaction(stakerBtcInfo: StakerInfo, stakingTx: Transaction, stakingTxHeight: number, stakingInput: StakingInputs, inclusionProof: InclusionProof, babylonAddress: string): Promise<{ signedBabylonTx: Uint8Array; }>; /** * Estimates the BTC fee required for staking. * @param stakerBtcInfo - The staker BTC info which includes the BTC address * and the no-coord public key in hex format. * @param babylonBtcTipHeight - The BTC tip height recorded on the Babylon * chain. * @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. 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(stakerBtcInfo: StakerInfo, babylonBtcTipHeight: number, stakingInput: StakingInputs, inputUTXOs: UTXO[], feeRate: number): number; /** * Creates a signed staking transaction that is ready to be sent to the BTC * network. * @param stakerBtcInfo - The staker BTC info which includes the BTC address * and the no-coord public key in hex format. * @param stakingInput - The staking inputs. * @param unsignedStakingTx - The unsigned staking transaction. * @param inputUTXOs - The UTXOs that will be used to pay for the staking * transaction. * @param stakingParamsVersion - The params version that was used to create the * delegation in Babylon chain * @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 * unbonding signatures need to be added to the transaction before sending it * to the BTC network. * NOTE: This method should only be used for Babylon phase-1 unbonding. * @param stakerBtcInfo - The staker BTC info which includes the BTC address * and the no-coord public key in hex format. * @param stakingInput - The staking inputs. * @param stakingParamsVersion - The params version that was used to create the * delegation in Babylon chain * @param stakingTx - The staking transaction. * @returns The partial signed unbonding transaction and its fee. */ createPartialSignedBtcUnbondingTransaction(stakerBtcInfo: StakerInfo, stakingInput: StakingInputs, stakingParamsVersion: number, stakingTx: Transaction): Promise<TransactionResult>; /** * Creates a signed unbonding transaction that is ready to be sent to the BTC * network. * @param stakerBtcInfo - The staker BTC info which includes the BTC address * and the no-coord public key in hex format. * @param stakingInput - The staking inputs. * @param stakingParamsVersion - The params version that was used to create the * delegation in Babylon chain * @param stakingTx - The staking transaction. * @param unsignedUnbondingTx - The unsigned unbonding transaction. * @param covenantUnbondingSignatures - The covenant unbonding signatures. * It can be retrieved from the Babylon chain or API. * @returns The signed unbonding transaction and its fee. */ createSignedBtcUnbondingTransaction(stakerBtcInfo: StakerInfo, stakingInput: StakingInputs, stakingParamsVersion: number, stakingTx: Transaction, unsignedUnbondingTx: Transaction, covenantUnbondingSignatures: { btcPkHex: string; sigHex: string; }[]): Promise<TransactionResult>; /** * Creates a signed withdrawal transaction on the unbodning output expiry path * that is ready to be sent to the BTC network. * @param stakingInput - The staking inputs. * @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. 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. */ createSignedBtcWithdrawEarlyUnbondedTransaction(stakerBtcInfo: StakerInfo, stakingInput: StakingInputs, stakingParamsVersion: number, earlyUnbondingTx: Transaction, feeRate: number): Promise<TransactionResult>; /** * Creates a signed withdrawal transaction on the staking output expiry path * that is ready to be sent to the BTC network. * @param stakerBtcInfo - The staker BTC info which includes the BTC address * and the no-coord public key in hex format. * @param stakingInput - The staking inputs. * @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. 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. */ createSignedBtcWithdrawStakingExpiredTransaction(stakerBtcInfo: StakerInfo, stakingInput: StakingInputs, stakingParamsVersion: number, stakingTx: Transaction, feeRate: number): Promise<TransactionResult>; /** * Creates a signed withdrawal transaction for the expired slashing output that * is ready to be sent to the BTC network. * @param stakerBtcInfo - The staker BTC info which includes the BTC address * and the no-coord public key in hex format. * @param stakingInput - The staking inputs. * @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. 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. */ createSignedBtcWithdrawSlashingTransaction(stakerBtcInfo: StakerInfo, stakingInput: StakingInputs, stakingParamsVersion: number, slashingTx: Transaction, feeRate: number): Promise<TransactionResult>; /** * Creates a proof of possession for the staker based on ECDSA signature. * @param bech32Address - The staker's bech32 address. * @returns The proof of possession. */ createProofOfPossession(channel: "delegation:create" | "delegation:register" | "delegation:expand", bech32Address: string, stakerBtcAddress: string): Promise<ProofOfPossessionBTC>; /** * Creates the unbonding, slashing, and unbonding slashing transactions and * PSBTs. * @param stakingInstance - The staking instance. * @param stakingTx - The staking transaction. * @returns The unbonding, slashing, and unbonding slashing transactions and * PSBTs. */ private createDelegationTransactionsAndPsbts; /** * Creates a protobuf message for the BTC delegation. * @param channel - The event channel to emit the message on. * @param stakingInstance - The staking instance. * @param stakingInput - The staking inputs. * @param stakingTx - The staking transaction. * @param bech32Address - The staker's babylon chain bech32 address * @param stakerBtcInfo - The staker's BTC information such as address and * public key * @param params - The staking parameters. * @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" | "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 | btcstakingtx.MsgBtcStakeExpand; }>; /** * Gets the inclusion proof for the staking transaction. * See the type `InclusionProof` for more information * @param inclusionProof - The inclusion proof. * @returns The inclusion proof. */ private getInclusionProof; } /** * Get the staker signature from the unbonding transaction * This is used mostly for unbonding transactions from phase-1(Observable) * @param unbondingTx - The unbonding transaction * @returns The staker signature */ export declare const getUnbondingTxStakerSignature: (unbondingTx: Transaction) => string; export interface ObservableStakingScripts extends StakingScripts { dataEmbedScript: Buffer; } export declare class ObservableStakingScriptData extends StakingScriptData { magicBytes: Buffer; constructor(stakerKey: Buffer, finalityProviderKeys: Buffer[], covenantKeys: Buffer[], covenantThreshold: number, stakingTimelock: number, unbondingTimelock: number, magicBytes: Buffer); /** * Builds a data embed script for staking in the form: * OP_RETURN || <serializedStakingData> * where serializedStakingData is the concatenation of: * MagicBytes || Version || StakerPublicKey || FinalityProviderPublicKey || StakingTimeLock * Note: Only a single finality provider key is supported for now in phase 1 * @throws {Error} If the number of finality provider keys is not equal to 1. * @returns {Buffer} The compiled data embed script. */ buildDataEmbedScript(): Buffer; /** * Builds the staking scripts. * @returns {ObservableStakingScripts} The staking scripts that can be used to stake. * contains the timelockScript, unbondingScript, slashingScript, * unbondingTimelockScript, and dataEmbedScript. * @throws {Error} If script data is invalid. */ buildScripts(): ObservableStakingScripts; } /** * ObservableStaking is a class that provides an interface to create observable * staking transactions for the Babylon Staking protocol. * * The class requires a network and staker information to create staking * transactions. * The staker information includes the staker's address and * public key(without coordinates). */ export declare class ObservableStaking extends Staking { params: ObservableVersionedStakingParams; constructor(network: networks.Network, stakerInfo: StakerInfo, params: ObservableVersionedStakingParams, finalityProviderPksNoCoordHex: string[], stakingTimelock: number); /** * Build the staking scripts for observable staking. * This method overwrites the base method to include the OP_RETURN tag based * on the tag provided in the parameters. * * @returns {ObservableStakingScripts} - The staking scripts for observable staking. * @throws {StakingError} - If the scripts cannot be built. */ buildScripts(): ObservableStakingScripts; /** * Create a staking transaction for observable staking. * This overwrites the method from the Staking class with the addtion * of the * 1. OP_RETURN tag in the staking scripts * 2. lockHeight parameter * * @param {number} stakingAmountSat - The amount to stake in satoshis. * @param {UTXO[]} inputUTXOs - The UTXOs to use as inputs for the staking * transaction. * @param {number} feeRate - The fee rate for the transaction in satoshis per byte. * @returns {TransactionResult} - An object containing the unsigned transaction, * and fee */ createStakingTransaction(stakingAmountSat: number, inputUTXOs: UTXO[], feeRate: number): TransactionResult; /** * Create a staking psbt for observable staking. * * @param {Transaction} stakingTx - The staking transaction. * @param {UTXO[]} inputUTXOs - The UTXOs to use as inputs for the staking * transaction. * @returns {Psbt} - The psbt. */ toStakingPsbt(stakingTx: Transaction, inputUTXOs: UTXO[]): Psbt; } export interface CovenantSignature { btcPkHex: string; sigHex: string; } /** * Constructs an unsigned BTC Staking transaction in psbt format. * * Outputs: * - psbt: * - The first output corresponds to the staking script with the specified amount. * - The second output corresponds to the change from spending the amount and the transaction fee. * - If a data embed script is provided, it will be added as the second output, and the fee will be the third output. * - fee: The total fee amount for the transaction. * * Inputs: * - scripts: * - timelockScript, unbondingScript, slashingScript: Scripts for different transaction types. * - dataEmbedScript: Optional data embed script. * - amount: Amount to stake. * - changeAddress: Address to send the change to. * - inputUTXOs: All available UTXOs from the wallet. * - network: Bitcoin network. * - feeRate: Fee rate in satoshis per byte. * - publicKeyNoCoord: Public key if the wallet is in taproot mode. * - lockHeight: Optional block height locktime to set for the transaction (i.e., not mined until the block height). * * @param {Object} scripts - Scripts used to construct the taproot output. * such as timelockScript, unbondingScript, slashingScript, and dataEmbedScript. * @param {number} amount - The amount to stake. * @param {string} changeAddress - The address to send the change to. * @param {UTXO[]} inputUTXOs - All available UTXOs from the wallet. * @param {networks.Network} network - The Bitcoin network. * @param {number} feeRate - The fee rate in satoshis per byte. * @param {number} [lockHeight] - The optional block height locktime. * @returns {TransactionResult} - An object containing the unsigned transaction and fee * @throws Will throw an error if the amount or fee rate is less than or equal * to 0, if the change address is invalid, or if the public key is invalid. */ export declare function stakingTransaction(scripts: { timelockScript: Buffer; unbondingScript: Buffer; 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. * * This transaction spends the unbonded output from the staking transaction. * * Inputs: * - scripts: Scripts used to construct the taproot output. * - unbondingTimelockScript: Script for the unbonding timelock condition. * - slashingScript: Script for the slashing condition. * - unbondingTx: The unbonding transaction. * - withdrawalAddress: The address to send the withdrawn funds to. * - network: The Bitcoin network. * - feeRate: The fee rate for the transaction in satoshis per byte. * * Returns: * - psbt: The partially signed transaction (PSBT). * * @param {Object} scripts - The scripts used in the transaction. * @param {Transaction} unbondingTx - The unbonding transaction. * @param {string} withdrawalAddress - The address to send the withdrawn funds to. * @param {networks.Network} network - The Bitcoin network. * @param {number} feeRate - The fee rate for the transaction in satoshis per byte. * @returns {PsbtResult} An object containing the partially signed transaction (PSBT). */ export declare function withdrawEarlyUnbondedTransaction(scripts: { unbondingTimelockScript: Buffer; slashingScript: Buffer; }, unbondingTx: Transaction, withdrawalAddress: string, network: networks.Network, feeRate: number): PsbtResult; /** * Constructs a withdrawal transaction for naturally unbonded delegation. * * This transaction spends the unbonded output from the staking transaction when the timelock has expired. * * Inputs: * - scripts: Scripts used to construct the taproot output. * - timelockScript: Script for the timelock condition. * - slashingScript: Script for the slashing condition. * - unbondingScript: Script for the unbonding condition. * - tx: The original staking transaction. * - withdrawalAddress: The address to send the withdrawn funds to. * - network: The Bitcoin network. * - feeRate: The fee rate for the transaction in satoshis per byte. * - outputIndex: The index of the output to be spent in the original transaction (default is 0). * * Returns: * - psbt: The partially signed transaction (PSBT). * * @param {Object} scripts - The scripts used in the transaction. * @param {Transaction} tx - The original staking transaction. * @param {string} withdrawalAddress - The address to send the withdrawn funds to. * @param {networks.Network} network - The Bitcoin network. * @param {number} feeRate - The fee rate for the transaction in satoshis per byte. * @param {number} [outputIndex=0] - The index of the output to be spent in the original transaction. * @returns {PsbtResult} An object containing the partially signed transaction (PSBT). */ export declare function withdrawTimelockUnbondedTransaction(scripts: { timelockScript: Buffer; slashingScript: Buffer; unbondingScript: Buffer; }, tx: Transaction, withdrawalAddress: string, network: networks.Network, feeRate: number, outputIndex?: number): PsbtResult; /** * Constructs a withdrawal transaction for a slashing transaction. * * This transaction spends the output from the slashing transaction. * * @param {Object} scripts - The unbondingTimelockScript * We use the unbonding timelock script as the timelock of the slashing transaction. * This is due to slashing tx timelock is the same as the unbonding timelock. * @param {Transaction} slashingTx - The slashing transaction. * @param {string} withdrawalAddress - The address to send the withdrawn funds to. * @param {networks.Network} network - The Bitcoin network. * @param {number} feeRate - The fee rate for the transaction in satoshis per byte. * @param {number} outputIndex - The index of the output to be spent in the original transaction. * @returns {PsbtResult} An object containing the partially signed transaction (PSBT). */ export declare function withdrawSlashingTransaction(scripts: { unbondingTimelockScript: Buffer; }, slashingTx: Transaction, withdrawalAddress: string, network: networks.Network, feeRate: number, outputIndex: number): PsbtResult; /** * Constructs a slashing transaction for a staking output without prior unbonding. * * This transaction spends the staking output of the staking transaction and distributes the funds * according to the specified slashing rate. * * Outputs: * - The first output sends `input * slashing_rate` funds to the slashing address. * - The second output sends `input * (1 - slashing_rate) - fee` funds back to the user's address. * * Inputs: * - scripts: Scripts used to construct the taproot output. * - slashingScript: Script for the slashing condition. * - timelockScript: Script for the timelock condition. * - unbondingScript: Script for the unbonding condition. * - unbondingTimelockScript: Script for the unbonding timelock condition. * - transaction: The original staking transaction. * - slashingAddress: The address to send the slashed funds to. * - slashingRate: The rate at which the funds are slashed (0 < slashingRate < 1). * - minimumFee: The minimum fee for the transaction in satoshis. * - network: The Bitcoin network. * - outputIndex: The index of the output to be spent in the original transaction (default is 0). * * @param {Object} scripts - The scripts used in the transaction. * @param {Transaction} stakingTransaction - The original staking transaction. * @param {string} slashingPkScriptHex - The public key script to send the slashed funds to. * @param {number} slashingRate - The rate at which the funds are slashed. * @param {number} minimumFee - The minimum fee for the transaction in satoshis. * @param {networks.Network} network - The Bitcoin network. * @param {number} [outputIndex=0] - The index of the output to be spent in the original transaction. * @returns {{ psbt: Psbt }} An object containing the partially signed transaction (PSBT). */ export declare function slashTimelockUnbondedTransaction(scripts: { slashingScript: Buffer; timelockScript: Buffer; unbondingScript: Buffer; unbondingTimelockScript: Buffer; }, stakingTransaction: Transaction, slashingPkScriptHex: string, slashingRate: number, minimumFee: number, network: networks.Network, outputIndex?: number): { psbt: Psbt; }; /** * Constructs a slashing transaction for an early unbonded transaction. * * This transaction spends the staking output of the staking transaction and distributes the funds * according to the specified slashing rate. * * Transaction outputs: * - The first output sends `input * slashing_rate` funds to the slashing address. * - The second output sends `input * (1 - slashing_rate) - fee` funds back to the user's address. * * @param {Object} scripts - The scripts used in the transaction. e.g slashingScript, unbondingTimelockScript * @param {Transaction} unbondingTx - The unbonding transaction. * @param {string} slashingPkScriptHex - The public key script to send the slashed funds to. * @param {number} slashingRate - The rate at which the funds are slashed. * @param {number} minimumSlashingFee - The minimum fee for the transaction in satoshis. * @param {networks.Network} network - The Bitcoin network. * @returns {{ psbt: Psbt }} An object containing the partially signed transaction (PSBT). */ export declare function slashEarlyUnbondedTransaction(scripts: { slashingScript: Buffer; unbondingTimelockScript: Buffer; }, unbondingTx: Transaction, slashingPkScriptHex: string, slashingRate: number, minimumSlashingFee: number, network: networks.Network): { psbt: Psbt; }; export declare function unbondingTransaction(scripts: { unbondingTimelockScript: Buffer; slashingScript: Buffer; }, stakingTx: Transaction, unbondingFee: number, network: networks.Network, outputIndex?: number): TransactionResult; export declare const createCovenantWitness: (originalWitness: Buffer[], paramsCovenants: Buffer[], covenantSigs: CovenantSignature[], covenantQuorum: number) => Buffer<ArrayBufferLike>[]; export declare const initBTCCurve: () => void; /** * Check whether the given address is a valid Bitcoin address. * * @param {string} btcAddress - The Bitcoin address to check. * @param {object} network - The Bitcoin network (e.g., bitcoin.networks.bitcoin). * @returns {boolean} - True if the address is valid, otherwise false. */ export declare const isValidBitcoinAddress: (btcAddress: string, network: networks.Network) => boolean; /** * Check whether the given address is a Taproot address. * * @param {string} taprootAddress - 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 Taproot address, otherwise false. */ export declare const isTaproot: (taprootAddress: string, network: networks.Network) => boolean; /** * 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 declare const isNativeSegwit: (segwitAddress: string, network: networks.Network) => boolean; /** * Check whether the given public key is a valid public key without a coordinate. * * @param {string} pkWithNoCoord - public key without the coordinate. * @returns {boolean} - True if the public key without the coordinate is valid, otherwise false. */ export declare const isValidNoCoordPublicKey: (pkWithNoCoord: string) => boolean; /** * Get the public key without the coordinate. * * @param {string} pkHex - The public key in hex, with or without the coordinate. * @returns {string} - The public key without the coordinate in hex. * @throws {Error} - If the public key is invalid. */ export declare const getPublicKeyNoCoord: (pkHex: string) => string; /** * Convert a transaction id to a hash. in buffer format. * * @param {string} txId - The transaction id. * @returns {Buffer} - The transaction hash. */ export declare const transactionIdToHash: (txId: string) => Buffer; export declare const getBabylonParamByBtcHeight: (height: number, babylonParamsVersions: VersionedStakingParams[]) => StakingParams; export declare const getBabylonParamByVersion: (version: number, babylonParams: VersionedStakingParams[]) => StakingParams; export declare const findInputUTXO: (inputUTXOs: UTXO[], input: Input) => UTXO; /** * Determines and constructs the correct PSBT input fields for a given UTXO based on its script type. * This function handles different Bitcoin script types (P2PKH, P2SH, P2WPKH, P2WSH, P2TR) and returns * the appropriate PSBT input fields required for that UTXO. * * @param {UTXO} utxo - The unspent transaction output to process