fedimint_server_core/
bitcoin_rpc.rs

1use std::fmt::Debug;
2use std::sync::{Arc, OnceLock};
3use std::time::Duration;
4
5use anyhow::{Context, 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            Feerate { sats_per_kvb: 1000 }
107        } else {
108            rpc.get_feerate().await?.context("Feerate not available")?
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        ensure!(
151            self.status_receiver.borrow().is_some(),
152            "Not connected to bitcoin backend"
153        );
154
155        self.rpc.submit_transaction(tx).await
156    }
157
158    /// Returns the chain ID, caching the result after the
159    /// first successful fetch.
160    pub async fn get_chain_id(&self) -> Result<ChainId> {
161        // Return cached value if available
162        if let Some(chain_id) = self.chain_id.get() {
163            return Ok(*chain_id);
164        }
165
166        ensure!(
167            self.status_receiver.borrow().is_some(),
168            "Not connected to bitcoin backend"
169        );
170
171        // Fetch from RPC and cache
172        let chain_id = self.rpc.get_chain_id().await?;
173        // It's OK if another task already set the value - the chain ID is immutable
174        let _ = self.chain_id.set(chain_id);
175
176        Ok(chain_id)
177    }
178}
179
180impl Clone for ServerBitcoinRpcMonitor {
181    fn clone(&self) -> Self {
182        Self {
183            rpc: self.rpc.clone(),
184            status_receiver: self.status_receiver.clone(),
185            chain_id: self
186                .chain_id
187                .get()
188                .copied()
189                .map(|h| {
190                    let lock = OnceLock::new();
191                    let _ = lock.set(h);
192                    lock
193                })
194                .unwrap_or_default(),
195        }
196    }
197}
198
199pub type DynServerBitcoinRpc = Arc<dyn IServerBitcoinRpc>;
200
201#[async_trait::async_trait]
202pub trait IServerBitcoinRpc: Debug + Send + Sync + 'static {
203    /// Returns the Bitcoin RPC config
204    fn get_bitcoin_rpc_config(&self) -> BitcoinRpcConfig;
205
206    /// Returns the Bitcoin RPC url
207    fn get_url(&self) -> SafeUrl;
208
209    /// Returns the current block count
210    async fn get_block_count(&self) -> Result<u64>;
211
212    /// Returns the block hash at a given height
213    ///
214    /// # Panics
215    /// If the node does not know a block for that height. Make sure to only
216    /// query blocks of a height less to the one returned by
217    /// `Self::get_block_count`.
218    ///
219    /// While there is a corner case that the blockchain shrinks between these
220    /// two calls (through on average heavier blocks on a fork) this is
221    /// prevented by only querying hashes for blocks tailing the chain tip
222    /// by a certain number of blocks.
223    async fn get_block_hash(&self, height: u64) -> Result<BlockHash>;
224
225    async fn get_block(&self, block_hash: &BlockHash) -> Result<Block>;
226
227    /// Estimates the fee rate for a given confirmation target. Make sure that
228    /// all federation members use the same algorithm to avoid widely
229    /// diverging results. If the node is not ready yet to return a fee rate
230    /// estimation this function returns `None`.
231    async fn get_feerate(&self) -> Result<Option<Feerate>>;
232
233    /// Submits a transaction to the Bitcoin network
234    ///
235    /// It is never OK to consider the success of this call as final, as the
236    /// caller should be retrying broadcast periodically until it confirms the
237    /// transaction was actually accepted via other means or decides that it is
238    /// no longer relevant. The returned `Result` is therefore purely
239    /// informational and callers are expected to log and ignore any error.
240    ///
241    /// Also - most backends considers brodcasting a tx that is already included
242    /// in the blockchain as an error, which breaks idempotency and requires
243    /// brittle workarounds just to reliably ignore... just to retry on the
244    /// higher level anyway.
245    async fn submit_transaction(&self, transaction: Transaction) -> Result<()>;
246
247    /// Returns the node's estimated chain sync percentage as a float between
248    /// 0.0 and 1.0, or `None` if the node doesn't support this feature.
249    async fn get_sync_progress(&self) -> Result<Option<f64>>;
250
251    /// Returns the chain ID (block hash at height 1)
252    ///
253    /// The chain ID uniquely identifies which Bitcoin network this node is
254    /// connected to. Use [`network_from_chain_id`] to derive the `Network`
255    /// enum from the chain ID.
256    async fn get_chain_id(&self) -> Result<ChainId>;
257
258    fn into_dyn(self) -> DynServerBitcoinRpc
259    where
260        Self: Sized,
261    {
262        Arc::new(self)
263    }
264}
fedimint_server_core/bitcoin_rpc.rs

fedimint_server_core/
bitcoin_rpc.rs
