bitcoin_ext/rpc/

mod.rs

#[cfg(feature = "rpc-socks5-proxy")]
mod socks5_transport;

pub use bdk_bitcoind_rpc::bitcoincore_rpc::{self, json, jsonrpc, Auth, Client, Error, RpcApi};

use std::borrow::Borrow;
use std::collections::HashMap;

#[cfg(feature = "rpc-async")]
use async_trait::async_trait;
use bdk_bitcoind_rpc::bitcoincore_rpc::Result as RpcResult;
#[cfg(feature = "rpc-async")]
use bitcoind_async_client::Client as AsyncClient;
#[cfg(feature = "rpc-async")]
use bitcoind_async_client::error::ClientError as AsyncClientError;
use bitcoin::address::NetworkUnchecked;
use bitcoin::hex::FromHex;
use bitcoin::{Address, Amount, FeeRate, Transaction, Txid, Weight};
#[cfg(feature = "rpc-async")]
use bitcoin::OutPoint;
use serde::{self, Deserialize, Serialize};
use serde::de::Error as SerdeError;

use crate::{BlockHeight, BlockRef, FeeRateExt, TxStatus, DEEPLY_CONFIRMED};

#[cfg(all(feature = "wasm-web", feature = "rpc-socks5-proxy"))]
compile_error!("`wasm-web` does not support the `rpc-socks5-proxy` feature");

/// Error code for RPC_VERIFY_ALREADY_IN_UTXO_SET.
pub const RPC_VERIFY_ALREADY_IN_UTXO_SET: i32 = -27;

/// Error code for RPC_INVALID_ADDRESS_OR_KEY, used when a tx is not found.
pub const RPC_INVALID_ADDRESS_OR_KEY: i32 = -5;

/// Clonable bitcoind rpc client.
///
/// Clones share the underlying [Client] and its single TCP connection.
/// The client can safely be used from multiple threads, but only one
/// request is in flight at a time: concurrent callers take turns on the
/// connection. Create separate clients if requests must run in parallel.
/// The connection is re-established transparently when it drops.
#[derive(Debug, Clone)]
pub struct BitcoinRpcClient {
	client: std::sync::Arc<Client>,
}

impl BitcoinRpcClient {
	pub fn new(url: &str, auth: Auth) -> Result<Self, Error> {
		Ok(BitcoinRpcClient {
			client: std::sync::Arc::new(Client::new(url, auth)?),
		})
	}
}

impl RpcApi for BitcoinRpcClient {
	fn call<T: for<'a> serde::de::Deserialize<'a>>(
		&self, cmd: &str, args: &[serde_json::Value],
	) -> Result<T, Error> {
		self.client.call(cmd, args)
	}
}

/// A module used for serde serialization of bytes in hexadecimal format.
///
/// The module is compatible with the serde attribute.
mod serde_hex {
	use bitcoin::hex::{DisplayHex, FromHex};
	use serde::de::Error;
	use serde::{Deserializer, Serializer};

	pub fn serialize<S: Serializer>(b: &Vec<u8>, s: S) -> Result<S::Ok, S::Error> {
		s.serialize_str(&b.to_lower_hex_string())
	}

	pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Vec<u8>, D::Error> {
		let hex_str: String = ::serde::Deserialize::deserialize(d)?;
		Ok(FromHex::from_hex(&hex_str).map_err(D::Error::custom)?)
	}

	pub mod opt {
		use bitcoin::hex::{DisplayHex, FromHex};
		use serde::de::Error;
		use serde::{Deserializer, Serializer};

		pub fn serialize<S: Serializer>(b: &Option<Vec<u8>>, s: S) -> Result<S::Ok, S::Error> {
			match *b {
				None => s.serialize_none(),
				Some(ref b) => s.serialize_str(&b.to_lower_hex_string()),
			}
		}

		pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Vec<u8>>, D::Error> {
			let hex_str: String = ::serde::Deserialize::deserialize(d)?;
			Ok(Some(FromHex::from_hex(&hex_str).map_err(D::Error::custom)?))
		}
	}
}

/// deserialize_hex_array_opt deserializes a vector of hex-encoded byte arrays.
fn deserialize_hex_array_opt<'de, D>(deserializer: D) -> Result<Option<Vec<Vec<u8>>>, D::Error>
where
	D: serde::Deserializer<'de>,
{
	//TODO(stevenroose) Revisit when issue is fixed:
	// https://github.com/serde-rs/serde/issues/723

	let v: Vec<String> = Vec::deserialize(deserializer)?;
	let mut res = Vec::new();
	for h in v.into_iter() {
		res.push(FromHex::from_hex(&h).map_err(D::Error::custom)?);
	}
	Ok(Some(res))
}

#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct GetRawTransactionResultVinScriptSig {
	pub asm: String,
	#[serde(with = "serde_hex")]
	pub hex: Vec<u8>,
}

#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct GetRawTransactionResultVin {
	pub sequence: u32,
	/// The raw scriptSig in case of a coinbase tx.
	#[serde(default, with = "serde_hex::opt")]
	pub coinbase: Option<Vec<u8>>,
	/// Not provided for coinbase txs.
	pub txid: Option<Txid>,
	/// Not provided for coinbase txs.
	pub vout: Option<u32>,
	/// The scriptSig in case of a non-coinbase tx.
	pub script_sig: Option<GetRawTransactionResultVinScriptSig>,
	/// Not provided for coinbase txs.
	#[serde(default, deserialize_with = "deserialize_hex_array_opt")]
	pub txinwitness: Option<Vec<Vec<u8>>>,
}

#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct GetRawTransactionResultVout {
	#[serde(with = "bitcoin::amount::serde::as_btc")]
	pub value: Amount,
	pub n: u32,
	pub script_pub_key: GetRawTransactionResultVoutScriptPubKey,
}

#[allow(non_camel_case_types)]
#[derive(Copy, Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum ScriptPubkeyType {
	Nonstandard,
	Anchor,
	Pubkey,
	PubkeyHash,
	ScriptHash,
	MultiSig,
	NullData,
	Witness_v0_KeyHash,
	Witness_v0_ScriptHash,
	Witness_v1_Taproot,
	Witness_Unknown,
}

#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct GetRawTransactionResultVoutScriptPubKey {
	pub asm: String,
	#[serde(with = "serde_hex")]
	pub hex: Vec<u8>,
	pub req_sigs: Option<usize>,
	#[serde(rename = "type")]
	pub type_: Option<ScriptPubkeyType>,
	// Deprecated in Bitcoin Core 22
	#[serde(default)]
	pub addresses: Vec<Address<NetworkUnchecked>>,
	// Added in Bitcoin Core 22
	#[serde(default)]
	pub address: Option<Address<NetworkUnchecked>>,
}

#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct GetRawTransactionResult {
	#[serde(rename = "in_active_chain")]
	pub in_active_chain: Option<bool>,
	#[serde(with = "serde_hex")]
	pub hex: Vec<u8>,
	pub txid: Txid,
	pub hash: bitcoin::Wtxid,
	pub size: usize,
	pub vsize: usize,
	pub version: u32,
	pub locktime: u32,
	pub vin: Vec<GetRawTransactionResultVin>,
	pub vout: Vec<GetRawTransactionResultVout>,
	pub blockhash: Option<bitcoin::BlockHash>,
	pub confirmations: Option<u32>,
	pub time: Option<usize>,
	pub blocktime: Option<usize>,
}

/// Result from the `submitpackage` RPC call.
#[derive(Clone, Debug, Deserialize)]
pub struct SubmitPackageResult {
	#[serde(rename = "tx-results")]
	pub tx_results: HashMap<bitcoin::Wtxid, SubmitPackageTxResult>,
	pub package_msg: String,
}

/// Per-transaction result from the `submitpackage` RPC call.
#[derive(Clone, Debug, Deserialize)]
pub struct SubmitPackageTxResult {
	pub txid: Txid,
	pub error: Option<String>,
}

/// Shorthand for converting a variable into a serde_json::Value.
fn into_json<T>(val: T) -> RpcResult<serde_json::Value>
where
	T: serde::ser::Serialize,
{
	Ok(serde_json::to_value(val)?)
}

/// Shorthand for converting an Option into an Option<serde_json::Value>.
fn opt_into_json<T>(opt: Option<T>) -> RpcResult<serde_json::Value>
where
	T: serde::ser::Serialize,
{
	match opt {
		Some(val) => Ok(into_json(val)?),
		None => Ok(serde_json::Value::Null),
	}
}

/// Handle default values in the argument list
///
/// Substitute `Value::Null`s with corresponding values from `defaults` table,
/// except when they are trailing, in which case just skip them altogether
/// in returned list.
///
/// Note, that `defaults` corresponds to the last elements of `args`.
///
/// ```norust
/// arg1 arg2 arg3 arg4
///           def1 def2
/// ```
///
/// Elements of `args` without corresponding `defaults` value, won't
/// be substituted, because they are required.
fn handle_defaults<'a, 'b>(
	args: &'a mut [serde_json::Value],
	defaults: &'b [serde_json::Value],
) -> &'a [serde_json::Value] {
	assert!(args.len() >= defaults.len());

	// Pass over the optional arguments in backwards order, filling in defaults after the first
	// non-null optional argument has been observed.
	let mut first_non_null_optional_idx = None;
	for i in 0..defaults.len() {
		let args_i = args.len() - 1 - i;
		let defaults_i = defaults.len() - 1 - i;
		if args[args_i] == serde_json::Value::Null {
			if first_non_null_optional_idx.is_some() {
				if defaults[defaults_i] == serde_json::Value::Null {
					panic!("Missing `default` for argument idx {}", args_i);
				}
				args[args_i] = defaults[defaults_i].clone();
			}
		} else if first_non_null_optional_idx.is_none() {
			first_non_null_optional_idx = Some(args_i);
		}
	}

	let required_num = args.len() - defaults.len();

	if let Some(i) = first_non_null_optional_idx {
		&args[..i + 1]
	} else {
		&args[..required_num]
	}
}

/// Shorthand for `serde_json::Value::Null`.
fn null() -> serde_json::Value {
	serde_json::Value::Null
}

pub trait BitcoinRpcErrorExt: Borrow<Error> {
	/// Whether this error indicates that the tx was not found.
	fn is_not_found(&self) -> bool {
		if let Error::JsonRpc(jsonrpc::Error::Rpc(e)) = self.borrow() {
			e.code == RPC_INVALID_ADDRESS_OR_KEY
		} else {
			false
		}
	}

	/// Whether this error indicates that the tx is already in the utxo set.
	fn is_in_utxo_set(&self) -> bool {
		if let Error::JsonRpc(jsonrpc::Error::Rpc(e)) = self.borrow() {
			e.code == RPC_VERIFY_ALREADY_IN_UTXO_SET
		} else {
			false
		}
	}

	fn is_already_in_mempool(&self) -> bool {
		if let Error::JsonRpc(jsonrpc::Error::Rpc(e)) = self.borrow() {
			e.message.contains("txn-already-in-mempool")
		} else {
			false
		}
	}
}
impl BitcoinRpcErrorExt for Error {}

pub trait BitcoinRpcExt: RpcApi {
	fn custom_get_raw_transaction_info(
		&self,
		txid: Txid,
		block_hash: Option<&bitcoin::BlockHash>,
	) -> RpcResult<Option<GetRawTransactionResult>> {
		let mut args = [into_json(txid)?, into_json(true)?, opt_into_json(block_hash)?];
		match self.call("getrawtransaction", handle_defaults(&mut args, &[null()])) {
			Ok(ret) => Ok(Some(ret)),
			Err(e) if e.is_not_found() => Ok(None),
			Err(e) => Err(e),
		}
	}

	fn broadcast_tx(&self, tx: &Transaction) -> Result<(), Error> {
		match self.send_raw_transaction(tx) {
			Ok(_) => Ok(()),
			Err(e) if e.is_in_utxo_set() => Ok(()),
			Err(e) => Err(e),
		}
	}

	fn tip(&self) -> Result<BlockRef, Error> {
		let height = self.get_block_count()?;
		let hash = self.get_block_hash(height)?;
		Ok(BlockRef { height: height as BlockHeight, hash })
	}

	fn deep_tip(&self) -> Result<BlockRef, Error> {
		let tip = self.get_block_count()?;
		let height = tip.saturating_sub(DEEPLY_CONFIRMED as u64);
		let hash = self.get_block_hash(height)?;
		Ok(BlockRef { height: height as BlockHeight, hash })
	}

	fn get_block_by_height(&self, height: BlockHeight) -> Result<BlockRef, Error> {
		let hash = self.get_block_hash(height as u64)?;
		Ok(BlockRef { height, hash })
	}

	fn tx_status(&self, txid: Txid) -> Result<TxStatus, Error> {
		match self.custom_get_raw_transaction_info(txid, None)? {
			Some(tx) => match tx.blockhash {
				Some(hash) => {
					let block = self.get_block_header_info(&hash)?;
					if block.confirmations > 0 {
						Ok(TxStatus::Confirmed(BlockRef { height: block.height as BlockHeight, hash: block.hash }))
					} else {
						Ok(TxStatus::Mempool)
					}
				},
				None => Ok(TxStatus::Mempool),
			},
			None => Ok(TxStatus::NotFound)
		}
	}

	fn submit_package(&self, txs: &[impl Borrow<Transaction>]) -> Result<SubmitPackageResult, Error> {
		let hexes = txs.iter()
			.map(|t| bitcoin::consensus::encode::serialize_hex(t.borrow()))
			.collect::<Vec<_>>();
		self.call("submitpackage", &[hexes.into()])
	}

	/// Get the transaction currently spending a given outpoint from the mempool.
	///
	/// Returns None if the outpoint is not being spent by any mempool transaction.
	fn get_mempool_spending_tx(
		&self,
		outpoint: bitcoin::OutPoint,
	) -> Result<Option<Txid>, Error> {
		// Get all mempool txids
		let mempool_txids: Vec<Txid> = self.call("getrawmempool", &[false.into()])?;

		for txid in mempool_txids {
			let tx = self.get_raw_transaction(&txid, None)?;
			for input in &tx.input {
				if input.previous_output == outpoint {
					return Ok(Some(txid));
				}
			}
		}
		Ok(None)
	}

	/// Estimate the effective feerate of a mempool transaction.
	///
	/// Returns the effective feerate considering ancestors and CPFP from direct descendants.
	/// Returns None if the transaction is not in the mempool.
	fn estimate_mempool_feerate(
		&self,
		txid: Txid,
	) -> RpcResult<Option<FeeRate>> {
		let entry = match self.get_mempool_entry(&txid) {
			Ok(e) => e,
			Err(e) if e.is_not_found() => return Ok(None),
			Err(e) => return Err(e),
		};

		let entry_feerate = |e: &json::GetMempoolEntryResult| -> Result<FeeRate, Error> {
			ancestor_feerate(e.fees.ancestor, e.ancestor_size)
				.ok_or(Error::UnexpectedStructure)
		};

		// Start with this tx's ancestor fee rate
		let mut feerate = entry_feerate(&entry)?;

		// Check direct descendants - if any has better ancestor rate, use that (CPFP)
		for descendant_txid in &entry.spent_by {
			if let Ok(desc_entry) = self.get_mempool_entry(descendant_txid) {
				feerate = std::cmp::max(feerate, entry_feerate(&desc_entry)?);
			}
		}

		Ok(Some(feerate))
	}
}

impl <T: RpcApi> BitcoinRpcExt for T {}

/// Effective feerate for a mempool entry given its ancestor fee total and
/// ancestor package size (in vbytes, as returned by `getmempoolentry`).
/// Returns `None` if the size is zero or the math overflows.
fn ancestor_feerate(ancestor_fee: Amount, ancestor_size_vb: u64) -> Option<FeeRate> {
	let weight = Weight::from_vb(ancestor_size_vb)?;
	FeeRate::from_amount_and_weight_ceil(ancestor_fee, weight)
}

/// Creates a bitcoind RPC client, optionally routing through a SOCKS5 proxy.
///
/// When no proxy is set, the standard transport is used.
/// When a proxy is set, a ureq-based transport routes traffic through the SOCKS5 proxy.
pub fn create_client(
	url: &str,
	auth: Auth,
	#[cfg(feature = "rpc-socks5-proxy")]
	socks5_proxy: Option<&str>,
) -> Result<Client, Error> {
	#[cfg(feature = "rpc-socks5-proxy")]
	if let Some(proxy) = socks5_proxy {
		let (user, pass) = auth.get_user_pass()?;
		let rpc_auth = user.map(|u| (u, pass));
		let transport = socks5_transport::Socks5Transport::new(url, proxy, rpc_auth)
			.map_err(|e| Error::JsonRpc(jsonrpc::Error::Transport(e.into())))?;

		return Ok(Client::from_jsonrpc(jsonrpc::Client::with_transport(transport)));
	}
	Client::new(url, auth)
}

/// Error from [BitcoinAsyncRpcExt::require_txindex].
#[cfg(feature = "rpc-async")]
#[derive(Debug, thiserror::Error)]
pub enum TxindexError {
	#[error("failed to getindexinfo from bitcoind")]
	Rpc(#[from] AsyncClientError),
	#[error("txindex is not enabled. Run bitcoind with txindex = 1")]
	NotEnabled,
}

/// How the async client reports a JSON-RPC `result` of `null`.
///
/// It has no typed representation for one: `Client::call` turns a missing result
/// into `ClientError::Other` carrying this message, and `call_raw` delegates to
/// `call`, so matching the message is the only way to tell a null result from a
/// genuine failure. Keep it in one place — were the upstream wording to change,
/// every caller of [BitcoinAsyncRpcExt::try_get_tx_out] would quietly stop recognising
/// a spent output.
#[cfg(feature = "rpc-async")]
const ASYNC_CLIENT_NULL_RESULT: &str = "Empty data received";

/// Extension trait for the async bitcoind rpc client.
#[cfg(feature = "rpc-async")]
#[async_trait]
pub trait BitcoinAsyncRpcExt {
	/// Checks that the connected bitcoind runs with `txindex=1`.
	async fn require_txindex(&self) -> Result<(), TxindexError>;

	/// `gettxout`, reporting the `null` of a spent or unknown output as `Ok(None)`.
	///
	/// Distinct from `Reader::get_tx_out`, which surfaces that `null` as an error.
	///
	/// Without `include_mempool` this reads the confirmed utxo set alone, so an
	/// output spent only by a mempool transaction still reports as present.
	async fn try_get_tx_out(
		&self,
		outpoint: OutPoint,
		include_mempool: bool,
	) -> Result<Option<json::GetTxOutResult>, AsyncClientError>;
}

#[cfg(feature = "rpc-async")]
#[async_trait]
impl BitcoinAsyncRpcExt for AsyncClient {
	async fn require_txindex(&self) -> Result<(), TxindexError> {
		let info: json::GetIndexInfoResult = self.call_raw("getindexinfo", &[]).await?;
		if info.txindex.is_none() {
			return Err(TxindexError::NotEnabled);
		}
		Ok(())
	}

	async fn try_get_tx_out(
		&self,
		outpoint: OutPoint,
		include_mempool: bool,
	) -> Result<Option<json::GetTxOutResult>, AsyncClientError> {
		let params = [
			serde_json::Value::String(outpoint.txid.to_string()),
			outpoint.vout.into(),
			include_mempool.into(),
		];
		match self.call_raw::<json::GetTxOutResult>("gettxout", &params).await {
			Ok(res) => Ok(Some(res)),
			Err(AsyncClientError::Other(msg)) if msg == ASYNC_CLIENT_NULL_RESULT => Ok(None),
			Err(e) => Err(e),
		}
	}
}

#[cfg(test)]
mod test {
	use super::*;

	// Regression: a previous implementation computed
	// `sat * (250 / ancestor_size)` due to integer-division precedence,
	// returning feerate 0 for any tx with `ancestor_size > 250` vbytes.

	#[test]
	fn ancestor_feerate_above_250_vbytes_is_nonzero() {
		// 1000 vbytes is well above the buggy threshold.
		// sat/kwu = ceil(10_000 * 1000 / (1000 * 4)) = 2_500
		let fr = ancestor_feerate(Amount::from_sat(10_000), 1_000).unwrap();
		assert_eq!(fr.to_sat_per_kwu(), 2_500);
	}

	#[test]
	fn ancestor_feerate_just_above_threshold() {
		// 251 vbytes - one above where the old code started returning 0.
		// sat/kwu = ceil(10_000 * 1000 / 1004) = ceil(9960.16) = 9_961
		let fr = ancestor_feerate(Amount::from_sat(10_000), 251).unwrap();
		assert_eq!(fr.to_sat_per_kwu(), 9_961);
	}

	#[test]
	fn ancestor_feerate_below_250_no_precision_loss() {
		// 100 vbytes - old code gave sat * 2 instead of sat * 2.5 (20% off).
		// sat/kwu = ceil(1_000 * 1000 / 400) = 2_500
		let fr = ancestor_feerate(Amount::from_sat(1_000), 100).unwrap();
		assert_eq!(fr.to_sat_per_kwu(), 2_500);
	}

	#[test]
	fn ancestor_feerate_zero_size_is_none() {
		assert_eq!(ancestor_feerate(Amount::from_sat(1_000), 0), None);
	}
}