caravan-x
Version:
A terminal-based utility for managing Caravan multisig wallets in regtest mode. This tool simplifies development and testing with Caravan by providing an easy-to-use interface
279 lines (278 loc) • 14.4 kB
TypeScript
import { BitcoinRpcConfig } from "../types/config";
/**
* Client for communicating with the Bitcoin Core via RPC
*/
export declare class BitcoinRpcClient {
readonly config: BitcoinRpcConfig;
readonly baseUrl: string;
readonly auth: {
username: string;
password: string;
};
constructor(config: BitcoinRpcConfig);
/**
* Call a Bitcoin Core RPC method (Inspired from `@caravan/clients` bitcoind method)
*/
/**
* Call a Bitcoin Core RPC method
*/
callRpc<T>(method: string, params?: any[], wallet?: string): Promise<T>;
/**
* Alternative method that uses bitcoin-cli command
*/
executeCliCommand(command: string, wallet?: string): string;
/**
* Lists all currently loaded wallets.
*
* This method calls the Bitcoin Core RPC method `listwallets`, which returns an array
* of wallet names that are currently loaded in the Bitcoin Core node.
*
* @returns {Promise<string[]>} A promise that resolves to an array of wallet names.
*
* @see https://developer.bitcoin.org/reference/rpc/listwallets.html
*/
listWallets(): Promise<string[]>;
/**
* Creates a new wallet.
*
* This method calls the Bitcoin Core RPC method `createwallet` with the following parameters:
* - `name`: The unique name for the new wallet.
* - `disablePrivateKeys`: If true, the wallet will be created without private keys (watch-only).
* - `blank`: If true, creates a blank wallet without an HD seed.
*
* Additional fixed parameters used in this call:
* - Passphrase is set to an empty string.
* - `avoid_reuse` is set to false.
* - `descriptors` is set to true.
* - `load_on_startup` is set to true.
*
* @param {string} name - The name of the wallet to be created.
* @param {boolean} [disablePrivateKeys=false] - Whether to disable private key generation.
* @param {boolean} [blank=false] - Whether to create a blank wallet.
* @returns {Promise<any>} A promise that resolves to the wallet creation result.
*
* @see https://developer.bitcoin.org/reference/rpc/createwallet.html
*/
createWallet(name: string, disablePrivateKeys?: boolean, blank?: boolean): Promise<any>;
/**
* Retrieves information about the specified wallet.
*
* This method calls the Bitcoin Core RPC method `getwalletinfo`, which returns an object
* containing various wallet details such as balance, transaction count, and more.
*
* @param {string} wallet - The name of the wallet.
* @returns {Promise<any>} A promise that resolves to an object containing wallet information.
*
* @see https://developer.bitcoin.org/reference/rpc/getwalletinfo.html
*/
getWalletInfo(wallet: string): Promise<any>;
/**
* Generates a new Bitcoin address for receiving funds.
*
* This method calls the Bitcoin Core RPC method `getnewaddress` with optional parameters:
* - `label`: An optional label for the new address.
* - `addressType`: The type of Bitcoin address to generate (default is `bech32`).
*
* @param {string} wallet - The wallet for which to generate the new address.
* @param {string} [label=''] - An optional label for the address.
* @param {string} [addressType='bech32'] - The type of address to generate (e.g., 'bech32', 'p2sh-segwit').
* @returns {Promise<string>} A promise that resolves to the newly generated Bitcoin address.
*
* @see https://developer.bitcoin.org/reference/rpc/getnewaddress.html
*/
getNewAddress(wallet: string, label?: string, addressType?: string): Promise<string>;
/**
* Retrieves detailed information about a specific Bitcoin address.
*
* This method calls the Bitcoin Core RPC method `getaddressinfo`, which provides details
* about the address (such as its script type, whether it is part of the wallet, etc.).
*
* @param {string} wallet - The wallet context to use.
* @param {string} address - The Bitcoin address to query.
* @returns {Promise<any>} A promise that resolves to an object containing address details.
*
* @see https://developer.bitcoin.org/reference/rpc/getaddressinfo.html
*/
getAddressInfo(wallet: string, address: string): Promise<any>;
/**
* Lists unspent transaction outputs (UTXOs) for the specified wallet.
*
* This method calls the Bitcoin Core RPC method `listunspent` with the following parameters:
* - `minConf`: The minimum number of confirmations required for UTXOs (default is 0).
* - `maxConf`: The maximum number of confirmations allowed (default is 9999999).
* - `addresses`: (Optional) A list of Bitcoin addresses to filter the UTXOs.
*
* @param {string} wallet - The wallet from which to list UTXOs.
* @param {number} [minConf=0] - The minimum confirmations a UTXO must have.
* @param {number} [maxConf=9999999] - The maximum confirmations a UTXO can have.
* @param {string[]} [addresses=[]] - An optional array of addresses to filter by.
* @returns {Promise<any[]>} A promise that resolves to an array of UTXO objects.
*
* @see https://developer.bitcoin.org/reference/rpc/listunspent.html
*/
listUnspent(wallet: string, minConf?: number, maxConf?: number, addresses?: string[]): Promise<any[]>;
/**
* Retrieves detailed information about a specific transaction.
*
* This method calls the Bitcoin Core RPC method `gettransaction`, which returns details
* about the specified transaction including confirmations, fee, and transaction details.
*
* @param {string} wallet - The wallet context to use for the transaction.
* @param {string} txid - The transaction ID (txid) of the transaction to retrieve.
* @returns {Promise<any>} A promise that resolves to an object containing transaction details.
*
* @see https://developer.bitcoin.org/reference/rpc/gettransaction.html
*/
getTransaction(wallet: string, txid: string): Promise<any>;
/**
* Sends an amount to a given address.
*
* This method calls the Bitcoin Core RPC method `sendtoaddress`, which creates a transaction
* sending the specified amount to the given address and broadcasts it to the network.
*
* @param {string} wallet - The wallet to send from.
* @param {string} address - The Bitcoin address to send to.
* @param {number} amount - The amount in BTC to send.
* @param {string} [comment=''] - Optional comment for the transaction.
* @param {string} [commentTo=''] - Optional comment about the recipient.
* @returns {Promise<string>} A promise that resolves to the transaction ID (txid).
*
* @see https://developer.bitcoin.org/reference/rpc/sendtoaddress.html
*/
sendToAddress(wallet: string, address: string, amount: number, comment?: string, commentTo?: string): Promise<string>;
/**
* Imports one or more descriptors into the specified wallet.
*
* This method calls the Bitcoin Core RPC method `importdescriptors`, which takes an array
* of descriptor objects. Descriptors define how addresses are derived (e.g., via public keys, scripts).
*
* Each descriptor object typically contains:
* - `desc`: The descriptor string.
* - `active`: A boolean indicating whether the descriptor is active.
* - `range`: The range of keys to scan (if applicable).
* - Additional keys as defined by Bitcoin Core documentation.
*
* @param {string} wallet - The wallet into which descriptors will be imported.
* @param {any[]} descriptors - An array of descriptor objects to be imported.
* @returns {Promise<any>} A promise that resolves to the result of the import operation.
*
* @see https://developer.bitcoin.org/reference/rpc/importdescriptors.html
*/
importDescriptors(wallet: string, descriptors: any[]): Promise<any>;
/**
* Creates a Partially Signed Bitcoin Transaction (PSBT) using the wallet's funds.
*
* This method calls the Bitcoin Core RPC method `walletcreatefundedpsbt` with the following parameters:
* - An empty array for inputs, letting Bitcoin Core automatically select UTXOs.
* - An array of output objects where each key is a Bitcoin address and each value is the amount in BTC.
* - A fee rate of 0 (which allows Bitcoin Core to estimate the fee).
* - An options object with `includeWatching` set to true, enabling the inclusion of watch-only addresses.
*
* @param {string} wallet - The wallet to use for creating the PSBT.
* @param {Record<string, number>[]} outputs - An array of objects mapping addresses to BTC amounts.
* @returns {Promise<any>} A promise that resolves to the created PSBT object.
*
* @see https://developer.bitcoin.org/reference/rpc/walletcreatefundedpsbt.html
*/
createPSBT(wallet: string, outputs: Record<string, number>[]): Promise<any>;
/**
* Processes a PSBT by attempting to sign it with the keys available in the wallet.
*
* This method calls the Bitcoin Core RPC method `walletprocesspsbt` which signs as many inputs as possible.
*
* @param {string} wallet - The wallet to use for processing the PSBT.
* @param {string} psbtBase64 - The base64-encoded PSBT string.
* @returns {Promise<any>} A promise that resolves to the processed PSBT object, possibly with partial signatures.
*
* @see https://developer.bitcoin.org/reference/rpc/walletprocesspsbt.html
*/
processPSBT(wallet: string, psbtBase64: string): Promise<any>;
/**
* Decodes a base64-encoded PSBT.
*
* This method calls the Bitcoin Core RPC method `decodepsbt` which returns a detailed JSON representation
* of the PSBT, including information about inputs, outputs, and any associated signatures.
*
* @param {string} psbtBase64 - The base64-encoded PSBT string to decode.
* @returns {Promise<any>} A promise that resolves to the decoded PSBT details.
*
* @see https://developer.bitcoin.org/reference/rpc/decodepsbt.html
*/
decodePSBT(psbtBase64: string): Promise<any>;
/**
* Finalizes a PSBT by completing all available signatures and assembling the final transaction.
*
* This method calls the Bitcoin Core RPC method `finalizepsbt`, which finalizes the PSBT. The response may
* include the complete raw transaction ready for broadcasting if all required signatures are present.
*
* @param {string} psbtBase64 - The base64-encoded PSBT string to finalize.
* @returns {Promise<any>} A promise that resolves to an object containing the finalized transaction details.
*
* @see https://developer.bitcoin.org/reference/rpc/finalizepsbt.html
*/
finalizePSBT(psbtBase64: string): Promise<any>;
/**
* Broadcasts a raw transaction to the Bitcoin network.
*
* This method calls the Bitcoin Core RPC method `sendrawtransaction`, which takes a hexadecimal string of
* the serialized transaction and broadcasts it to the network.
*
* @param {string} hexstring - The raw transaction in hexadecimal format.
* @returns {Promise<string>} A promise that resolves to the transaction ID (txid) of the broadcast transaction.
*
* @see https://developer.bitcoin.org/reference/rpc/sendrawtransaction.html
*/
sendRawTransaction(hexstring: string): Promise<string>;
/**
* Retrieves general information about the current state of the blockchain.
*
* This method calls the Bitcoin Core RPC method `getblockchaininfo`, which provides data such as the
* current chain, network, number of blocks, and verification progress.
*
* @returns {Promise<any>} A promise that resolves to an object containing blockchain information.
*
* @see https://developer.bitcoin.org/reference/rpc/getblockchaininfo.html
*/
getBlockchainInfo(): Promise<any>;
/**
* Mines a specified number of blocks and sends the block rewards to a given address.
*
* This method calls the Bitcoin Core RPC method `generatetoaddress`, which generates new blocks and
* directs the coinbase rewards to the specified address.
*
* @param {number} blocks - The number of blocks to generate.
* @param {string} address - The Bitcoin address to receive the mining rewards.
* @returns {Promise<string[]>} A promise that resolves to an array of block hashes for the mined blocks.
*
* @see https://developer.bitcoin.org/reference/rpc/generatetoaddress.html
*/
generateToAddress(blocks: number, address: string): Promise<string[]>;
/**
* Estimates the fee rate (in BTC/kB) required for a transaction to be confirmed within a specified number of blocks.
*
* This method calls the Bitcoin Core RPC method `estimatesmartfee`. The fee estimate helps users determine an
* appropriate fee to use to have their transaction confirmed within the target number of blocks.
*
* @param {number} [blocks=6] - The target number of blocks within which the transaction should be confirmed.
* @returns {Promise<any>} A promise that resolves to an object containing the estimated fee rate and additional details.
*
* @see https://developer.bitcoin.org/reference/rpc/estimatesmartfee.html
*/
estimateSmartFee(blocks?: number): Promise<any>;
/**
* Retrieves detailed information about a specific block.
*
* This method calls the Bitcoin Core RPC method `getblock`, which returns data such as the block's size,
* transactions, and header information. The verbosity parameter controls how much detail is returned:
* - A verbosity of 1 returns a JSON object with basic information.
* - Higher verbosity levels return more detailed data.
*
* @param {string} blockhash - The hash of the block to retrieve.
* @param {number} [verbosity=1] - The verbosity level (default is 1).
* @returns {Promise<any>} A promise that resolves to an object containing block details.
*
* @see https://developer.bitcoin.org/reference/rpc/getblock.html
*/
getBlock(blockhash: string, verbosity?: number): Promise<any>;
isWalletAddressNotFoundError(error: any): boolean;
}