fedimint_server_core/
bitcoin_rpc.rs

1use std::fmt::Debug;
2use std::sync::{Arc, OnceLock};
3use std::time::Duration;
4
5use anyhow::{Result, ensure};
6use fedimint_core::bitcoin::{Block, BlockHash, Network, Transaction};
7use fedimint_core::envs::BitcoinRpcConfig;
8use fedimint_core::task::TaskGroup;
9use fedimint_core::util::{FmtCompactAnyhow as _, SafeUrl};
10use fedimint_core::{ChainId, Feerate};
11use fedimint_logging::LOG_SERVER;
12use tokio::sync::watch;
13use tracing::{debug, warn};
14
15use crate::dashboard_ui::ServerBitcoinRpcStatus;
16
17// Well-known genesis block hashes for different Bitcoin networks
18// <https://blockstream.info/api/block-height/1>
19const MAINNET_CHAIN_ID_STR: &str =
20    "00000000839a8e6886ab5951d76f411475428afc90947ee320161bbf18eb6048";
21// <https://blockstream.info/testnet/api/block-height/1>
22const TESTNET_CHAIN_ID_STR: &str =
23    "00000000b873e79784647a6c82962c70d228557d24a747ea4d1b8bbe878e1206";
24// <https://mempool.space/signet/api/block-height/1>
25const SIGNET_4_CHAIN_ID_STR: &str =
26    "00000086d6b2636cb2a392d45edc4ec544a10024d30141c9adf4bfd9de533b53";
27// <https://mutinynet.com/api/block-height/1>
28const MUTINYNET_CHAIN_ID_STR: &str =
29    "000002855893a0a9b24eaffc5efc770558a326fee4fc10c9da22fc19cd2954f9";
30
31/// Derives the Bitcoin network from a chain ID (block height 1 block hash).
32///
33/// Returns the corresponding `Network` for well-known genesis hashes,
34/// or `Network::Regtest` for unknown hashes (custom/private networks).
35pub fn network_from_chain_id(chain_id: ChainId) -> Network {
36    match chain_id.to_string().as_str() {
37        MAINNET_CHAIN_ID_STR => Network::Bitcoin,
38        TESTNET_CHAIN_ID_STR => Network::Testnet,
39        SIGNET_4_CHAIN_ID_STR => Network::Signet,
40        MUTINYNET_CHAIN_ID_STR => Network::Signet,
41        _ => {
42            // Unknown genesis hash - treat as regtest/custom network
43            Network::Regtest
44        }
45    }
46}
47
48#[derive(Debug)]
49pub struct ServerBitcoinRpcMonitor {
50    rpc: DynServerBitcoinRpc,
51    status_receiver: watch::Receiver<Option<ServerBitcoinRpcStatus>>,
52    /// Cached chain ID (block hash at height 1) - fetched once and never
53    /// changes
54    chain_id: OnceLock<ChainId>,
55}
56
57impl ServerBitcoinRpcMonitor {
58    pub fn new(
59        rpc: DynServerBitcoinRpc,
60        update_interval: Duration,
61        task_group: &TaskGroup,
62    ) -> Self {
63        let (status_sender, status_receiver) = watch::channel(None);
64
65        let rpc_clone = rpc.clone();
66        debug!(
67            target: LOG_SERVER,
68            interval_ms  = %update_interval.as_millis(),
69            "Starting bitcoin rpc monitor"
70        );
71
72        task_group.spawn_cancellable("bitcoin-status-update", async move {
73            let mut interval = tokio::time::interval(update_interval);
74            loop {
75                interval.tick().await;
76                match Self::fetch_status(&rpc_clone).await {
77                    Ok(new_status) => {
78                        status_sender.send_replace(Some(new_status));
79                    }
80                    Err(err) => {
81                        warn!(
82                            target: LOG_SERVER,
83                            err = %err.fmt_compact_anyhow(),
84                            "Bitcoin status update failed"
85                        );
86                        status_sender.send_replace(None);
87                    }
88                }
89            }
90        });
91
92        Self {
93            rpc,
94            status_receiver,
95            chain_id: OnceLock::new(),
96        }
97    }
98
99    async fn fetch_status(rpc: &DynServerBitcoinRpc) -> Result<ServerBitcoinRpcStatus> {
100        let chain_id = rpc.get_chain_id().await?;
101        let network = network_from_chain_id(chain_id);
102        let block_count = rpc.get_block_count().await?;
103        let sync_progress = rpc.get_sync_progress().await?;
104
105        let fee_rate = if network == Network::Regtest {
106            Some(Feerate { sats_per_kvb: 1000 })
107        } else {
108            rpc.get_feerate().await?
109        };
110
111        Ok(ServerBitcoinRpcStatus {
112            network,
113            block_count,
114            fee_rate,
115            sync_progress,
116        })
117    }
118
119    pub fn get_bitcoin_rpc_config(&self) -> BitcoinRpcConfig {
120        self.rpc.get_bitcoin_rpc_config()
121    }
122
123    pub fn url(&self) -> SafeUrl {
124        self.rpc.get_url()
125    }
126
127    pub fn status(&self) -> Option<ServerBitcoinRpcStatus> {
128        self.status_receiver.borrow().clone()
129    }
130
131    pub async fn get_block(&self, hash: &BlockHash) -> Result<Block> {
132        ensure!(
133            self.status_receiver.borrow().is_some(),
134            "Not connected to bitcoin backend"
135        );
136
137        self.rpc.get_block(hash).await
138    }
139
140    pub async fn get_block_hash(&self, height: u64) -> Result<BlockHash> {
141        ensure!(
142            self.status_receiver.borrow().is_some(),
143            "Not connected to bitcoin backend"
144        );
145
146        self.rpc.get_block_hash(height).await
147    }
148
149    pub async fn submit_transaction(&self, tx: Transaction) -> Result<()> {
150        self.rpc.submit_transaction(tx).await
151    }
152
153    /// Returns the chain ID, caching the result after the
154    /// first successful fetch.
155    pub async fn get_chain_id(&self) -> Result<ChainId> {
156        // Return cached value if available
157        if let Some(chain_id) = self.chain_id.get() {
158            return Ok(*chain_id);
159        }
160
161        ensure!(
162            self.status_receiver.borrow().is_some(),
163            "Not connected to bitcoin backend"
164        );
165
166        // Fetch from RPC and cache
167        let chain_id = self.rpc.get_chain_id().await?;
168        // It's OK if another task already set the value - the chain ID is immutable
169        let _ = self.chain_id.set(chain_id);
170
171        Ok(chain_id)
172    }
173}
174
175impl Clone for ServerBitcoinRpcMonitor {
176    fn clone(&self) -> Self {
177        Self {
178            rpc: self.rpc.clone(),
179            status_receiver: self.status_receiver.clone(),
180            chain_id: self
181                .chain_id
182                .get()
183                .copied()
184                .map(|h| {
185                    let lock = OnceLock::new();
186                    let _ = lock.set(h);
187                    lock
188                })
189                .unwrap_or_default(),
190        }
191    }
192}
193
194pub type DynServerBitcoinRpc = Arc<dyn IServerBitcoinRpc>;
195
196#[async_trait::async_trait]
197pub trait IServerBitcoinRpc: Debug + Send + Sync + 'static {
198    /// Returns the Bitcoin RPC config
199    fn get_bitcoin_rpc_config(&self) -> BitcoinRpcConfig;
200
201    /// Returns the Bitcoin RPC url
202    fn get_url(&self) -> SafeUrl;
203
204    /// Returns the current block count
205    async fn get_block_count(&self) -> Result<u64>;
206
207    /// Returns the current block count and whether initial block download is
208    /// still active.
209    ///
210    /// Backends without an explicit IBD flag are assumed ready. Full nodes
211    /// should override this method when both values come from one status call.
212    async fn get_block_count_and_initial_block_download(&self) -> Result<(u64, bool)> {
213        Ok((self.get_block_count().await?, false))
214    }
215
216    /// Returns the block hash at a given height
217    ///
218    /// # Panics
219    /// If the node does not know a block for that height. Make sure to only
220    /// query blocks of a height less to the one returned by
221    /// `Self::get_block_count`.
222    ///
223    /// While there is a corner case that the blockchain shrinks between these
224    /// two calls (through on average heavier blocks on a fork) this is
225    /// prevented by only querying hashes for blocks tailing the chain tip
226    /// by a certain number of blocks.
227    async fn get_block_hash(&self, height: u64) -> Result<BlockHash>;
228
229    async fn get_block(&self, block_hash: &BlockHash) -> Result<Block>;
230
231    /// Estimates the fee rate for a given confirmation target. Make sure that
232    /// all federation members use the same algorithm to avoid widely
233    /// diverging results. If the node is not ready yet to return a fee rate
234    /// estimation this function returns `None`.
235    async fn get_feerate(&self) -> Result<Option<Feerate>>;
236
237    /// Submits a transaction to the Bitcoin network
238    ///
239    /// It is never OK to consider the success of this call as final, as the
240    /// caller should be retrying broadcast periodically until it confirms the
241    /// transaction was actually accepted via other means or decides that it is
242    /// no longer relevant. The returned `Result` is therefore purely
243    /// informational and callers are expected to log and ignore any error.
244    ///
245    /// Also - most backends considers brodcasting a tx that is already included
246    /// in the blockchain as an error, which breaks idempotency and requires
247    /// brittle workarounds just to reliably ignore... just to retry on the
248    /// higher level anyway.
249    async fn submit_transaction(&self, transaction: Transaction) -> Result<()>;
250
251    /// Returns the node's estimated chain sync percentage as a float between
252    /// 0.0 and 1.0, or `None` if the node doesn't support this feature.
253    async fn get_sync_progress(&self) -> Result<Option<f64>>;
254
255    /// Returns the chain ID (block hash at height 1)
256    ///
257    /// The chain ID uniquely identifies which Bitcoin network this node is
258    /// connected to. Use [`network_from_chain_id`] to derive the `Network`
259    /// enum from the chain ID.
260    async fn get_chain_id(&self) -> Result<ChainId>;
261
262    fn into_dyn(self) -> DynServerBitcoinRpc
263    where
264        Self: Sized,
265    {
266        Arc::new(self)
267    }
268}
fedimint_server_core/bitcoin_rpc.rs

fedimint_server_core/
bitcoin_rpc.rs
