rustywallet_electrum/
lib.rs

1//! # rustywallet-electrum
2//!
3//! Electrum protocol client for Bitcoin balance checking and UTXO fetching.
4//!
5//! This crate provides an async client for communicating with Electrum servers,
6//! allowing you to query blockchain data without rate limits.
7//!
8//! ## Features
9//!
10//! - **Balance checking** - Get confirmed and unconfirmed balance for any address
11//! - **Batch queries** - Check multiple addresses efficiently in a single request
12//! - **UTXO listing** - Get unspent outputs for transaction building
13//! - **Transaction operations** - Get raw transactions and broadcast signed ones
14//! - **TLS support** - Secure connections to Electrum servers
15//! - **Certificate pinning** - Enhanced security with SSL certificate pinning
16//! - **Server discovery** - DNS-based server discovery
17//! - **Connection pooling** - Efficient connection management
18//! - **Real-time subscriptions** - Address and header change notifications
19//!
20//! ## Quick Start
21//!
22//! ```no_run
23//! use rustywallet_electrum::{ElectrumClient, ClientConfig};
24//!
25//! #[tokio::main]
26//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
27//!     // Connect to a public Electrum server
28//!     let client = ElectrumClient::new("electrum.blockstream.info").await?;
29//!     
30//!     // Check server connection
31//!     let version = client.server_version().await?;
32//!     println!("Connected to: {}", version.server_software);
33//!     
34//!     // Get balance for an address
35//!     let balance = client.get_balance("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa").await?;
36//!     println!("Confirmed: {} sats", balance.confirmed);
37//!     println!("Unconfirmed: {} sats", balance.unconfirmed);
38//!     
39//!     // Batch check multiple addresses
40//!     let addresses = vec![
41//!         "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
42//!         "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
43//!     ];
44//!     let balances = client.get_balances(&addresses).await?;
45//!     for (addr, bal) in addresses.iter().zip(balances.iter()) {
46//!         println!("{}: {} sats", addr, bal.confirmed);
47//!     }
48//!     
49//!     Ok(())
50//! }
51//! ```
52//!
53//! ## Server Discovery
54//!
55//! ```no_run
56//! use rustywallet_electrum::discovery::ServerDiscovery;
57//!
58//! #[tokio::main]
59//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
60//!     let discovery = ServerDiscovery::new();
61//!     let best = discovery.best_server().await?;
62//!     println!("Best server: {} ({}ms)", best.hostname, best.latency_ms.unwrap_or(0));
63//!     Ok(())
64//! }
65//! ```
66//!
67//! ## Connection Pooling
68//!
69//! ```no_run
70//! use rustywallet_electrum::{ClientConfig, pool::{ConnectionPool, PoolConfig}};
71//!
72//! #[tokio::main]
73//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
74//!     let config = ClientConfig::ssl("electrum.blockstream.info");
75//!     let pool = ConnectionPool::new(config, PoolConfig::default());
76//!     pool.initialize().await?;
77//!     
78//!     let client = pool.acquire().await?;
79//!     let balance = client.get_balance("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa").await?;
80//!     // Connection automatically returned to pool when dropped
81//!     Ok(())
82//! }
83//! ```
84//!
85//! ## Address Support
86//!
87//! All Bitcoin address types are supported:
88//! - P2PKH (1...)
89//! - P2SH (3...)
90//! - P2WPKH (bc1q...)
91//! - P2WSH (bc1q... longer)
92//! - P2TR (bc1p...)
93//!
94//! ## Public Servers
95//!
96//! Built-in list of public Electrum servers:
97//! - `electrum.blockstream.info:50002` (SSL)
98//! - `electrum1.bluewallet.io:443` (SSL)
99//! - `bitcoin.aranguren.org:50002` (SSL)
100//!
101//! ## Custom Configuration
102//!
103//! ```no_run
104//! use rustywallet_electrum::{ElectrumClient, ClientConfig};
105//! use std::time::Duration;
106//!
107//! #[tokio::main]
108//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
109//!     let config = ClientConfig::ssl("electrum.blockstream.info")
110//!         .with_port(50002)
111//!         .with_timeout(Duration::from_secs(60))
112//!         .with_retry(5, Duration::from_secs(2));
113//!     
114//!     let client = ElectrumClient::with_config(config).await?;
115//!     Ok(())
116//! }
117//! ```
118
119#![warn(missing_docs)]
120#![warn(rustdoc::missing_crate_level_docs)]
121
122pub mod batch;
123pub mod client;
124pub mod discovery;
125pub mod error;
126pub mod pinning;
127pub mod pool;
128pub mod scripthash;
129pub mod subscription;
130pub mod transport;
131pub mod types;
132
133// Re-exports
134pub use client::ElectrumClient;
135pub use error::{ElectrumError, Result};
136pub use scripthash::{address_to_scripthash, addresses_to_scripthashes};
137pub use types::{Balance, ClientConfig, ServerVersion, TxHistory, Utxo, DEFAULT_SERVERS};
138
139// New v0.2 re-exports
140pub use batch::{BatchRequest, BatchResponse, GapLimitScanner, ParallelBatchExecutor};
141pub use discovery::{DiscoveredServer, ServerDiscovery, DNS_SEEDS};
142pub use pinning::{CertFingerprint, CertPinStore, PinningConfigBuilder};
143pub use pool::{ConnectionPool, PoolConfig, PoolStats, PooledClient};
144pub use subscription::{
145    AddressStatusEvent, AddressWatcher, BlockHeaderEvent, ConnectionStatus,
146    SubscriptionClient, SubscriptionEvent, SubscriptionManager,
147};
rustywallet_electrum/lib.rs

rustywallet_electrum/
lib.rs
