Struct ChainSource 

pub struct ChainSource { /* private fields */ }

Client for interacting with the configured on-chain backend.

ChainSource abstracts over multiple backends using ChainSourceSpec to provide:

• Chain queries (tip, block headers/blocks, transaction status and fetching)
• Mempool-related utilities (ancestor fee/weight, spending lookups)
• Broadcasting single transactions or packages (RBF/CPFP workflows)
• Fee estimation and caching with optional fallback values

Behavior notes:

• ChainSource::update_fee_rates refreshes internal fee estimates; if backend estimates fail and a fallback fee is provided, it will be used for all tiers.
• ChainSource::fee_rates returns the last cached FeeRates.

Examples:

use bark::chain::{ChainSource, ChainSourceSpec};
use bdk_bitcoind_rpc::bitcoincore_rpc::Auth;
use bitcoin::{FeeRate, Network};

let spec = ChainSourceSpec::Bitcoind {
    url: "http://localhost:8332".into(),
    auth: Auth::UserPass("user".into(), "password".into()),
    zmq: None,
};
let network = Network::Bitcoin;
let fallback_fee = FeeRate::from_sat_per_vb(5);
#[cfg(feature = "socks5-proxy")]
let socks5 = Some("socks5h://127.0.0.1:9050");

let instance = ChainSource::new(spec, network, fallback_fee, socks5).await.unwrap();

Implementations

impl ChainSource

pub async fn require_version(&self) -> Result<()>

Checks that the version of the chain source is compatible with Bark.

For bitcoind, it checks if the version is at least 29.0 This is the first version for which 0 fee-anchors are considered standard

pub async fn fee_rates(&self) -> FeeRates

Gets a cached copy of the calculated network FeeRates

pub fn network(&self) -> Network

Gets the network that the ChainSource was validated against.

pub async fn new( spec: ChainSourceSpec, network: Network, fallback_fee: Option<FeeRate>, ) -> Result<Self>

Creates a new instance of the object with the specified chain source, network, and optional fallback fee rate.

This function initializes the internal chain source client based on the provided chain_source:

• If chain_source is of type ChainSourceSpec::Bitcoind, it creates a Bitcoin Core RPC client using the provided URL and authentication parameters.
• If chain_source is of type ChainSourceSpec::Esplora, it creates an Esplora client with the given URL.

Both clients are initialized asynchronously, and any errors encountered during their creation will be returned as part of the anyhow::Result.

Additionally, the function performs a network consistency check to ensure the specified network (e.g., mainnet or signet) matches the network configuration of the initialized chain source client.

The fallback_fee parameter is optional. If provided, it is used as the default fee rate for transactions. If not specified, the FeeRate::BROADCAST_MIN is used as the default fee rate.

Arguments

• chain_source - Specifies the backend to use for blockchain data.
• network - The Bitcoin network to operate on (e.g., mainnet, testnet, regtest).
• fallback_fee - An optional fallback fee rate to use for transaction fee estimation. If not provided, a default fee rate of FeeRate::BROADCAST_MIN will be used.

Returns

• Ok(Self) - If the object is successfully created with all necessary configurations.
• Err(anyhow::Error) - If there is an error in initializing the chain source client or verifying the network.

pub fn zmq_endpoint(&self) -> Option<&str>

The ZMQ endpoint of the bitcoind backend, if one was configured.

Always None for the Esplora backend.

pub async fn tip(&self) -> Result<BlockHeight>

pub async fn invalidate_caches(&self)

Drop the cached tip and fee-rate values, forcing the next call to tip() or update_fee_rates() to round-trip the backend. Useful in tests that fabricate chain changes faster than the TTL so the next observation is deterministic without sleeping.

pub async fn tip_ref(&self) -> Result<BlockRef>

pub async fn tip_watcher( self: &Arc<Self>, poll_interval: Duration, ) -> Result<TipWatcher>

Starts a TipWatcher tracking the chain tip of this source.

When this source has a ZMQ endpoint configured, block notifications wake the watcher and poll_interval becomes the reconcile interval; otherwise the tip is polled at poll_interval.

pub async fn block_ref(&self, height: BlockHeight) -> Result<BlockRef>

pub async fn block(&self, hash: BlockHash) -> Result<Option<Block>>

pub async fn mempool_ancestor_info( &self, txid: Txid, ) -> Result<MempoolAncestorInfo>

Retrieves basic CPFP ancestry information of the given transaction. Confirmed transactions are ignored as they are not relevant to CPFP.

pub async fn txs_spending_inputs<T: IntoIterator<Item = OutPoint>>( &self, outpoints: T, block_scan_start: BlockHeight, ) -> Result<TxsSpendingInputsResult>

For each provided outpoint, fetches the ID of any confirmed or unconfirmed in which the outpoint is spent.

pub async fn broadcast_tx(&self, tx: &Transaction) -> Result<()>

pub async fn broadcast_package( &self, txs: &[impl Borrow<Transaction>], ) -> Result<(), BroadcastError>

pub async fn get_tx(&self, txid: &Txid) -> Result<Option<Transaction>>

pub async fn tx_confirmed(&self, txid: Txid) -> Result<Option<BlockHeight>>

Returns the block height the tx is confirmed in, if any.

pub async fn tx_status(&self, txid: Txid) -> Result<TxStatus>

Returns the status of the given transaction, including the block height if it is confirmed

pub async fn txout_value(&self, outpoint: &OutPoint) -> Result<Amount>

pub async fn outpoint_spent_confirmed(&self, outpoint: OutPoint) -> Result<bool>

Whether outpoint has been spent by a transaction that is confirmed, i.e. whether any transaction spending it can still be mined.

A spend sitting only in the mempool reports false: it can still be replaced, so it decides nothing.

The caller must know outpoint’s own transaction is confirmed. gettxout reads the confirmed utxo set, so it cannot tell an output spent on-chain apart from one whose transaction has yet to be mined.

pub async fn update_fee_rates( &self, fallback_fee: Option<FeeRate>, ) -> Result<()>

Gets the current fee rates from the chain source, falling back to user-specified values if necessary.

No-ops if a previous successful call ran within FEE_RATES_CACHE_TTL. The fallback path overwrites the cached rates but deliberately does not advance the cache timestamp, so the next call retries the backend instead of serving the fallback for another full TTL.

Trait Implementations

impl TipSource for ChainSource

async fn tip_ref(&self) -> Result<BlockRef>