bitcoind_async_client/
traits.rs

1use bitcoin::{bip32::Xpriv, block::Header, Address, Block, BlockHash, Network, Transaction, Txid};
2use std::future::Future;
3
4use crate::{
5    client::ClientResult,
6    types::{
7        CreateRawTransaction, GetBlockchainInfo, GetRawTransactionVerbosityOne,
8        GetRawTransactionVerbosityZero, GetTransaction, GetTxOut, ImportDescriptor,
9        ImportDescriptorResult, ListTransactions, ListUnspent, PreviousTransactionOutput,
10        SignRawTransactionWithWallet, SubmitPackage, TestMempoolAccept,
11    },
12};
13
14/// Basic functionality that any Bitcoin client that interacts with the
15/// Bitcoin network should provide.
16///
17/// # Note
18///
19/// This is a fully `async` trait. The user should be responsible for
20/// handling the `async` nature of the trait methods. And if implementing
21/// this trait for a specific type that is not `async`, the user should
22/// consider wrapping with [`tokio`](https://tokio.rs)'s
23/// [`spawn_blocking`](https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html) or any other method.
24pub trait Reader {
25    /// Estimates the approximate fee per kilobyte needed for a transaction
26    /// to begin confirmation within conf_target blocks if possible and return
27    /// the number of blocks for which the estimate is valid.
28    ///
29    /// # Parameters
30    ///
31    /// - `conf_target`: Confirmation target in blocks.
32    ///
33    /// # Note
34    ///
35    /// Uses virtual transaction size as defined in
36    /// [BIP 141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki)
37    /// (witness data is discounted).
38    ///
39    /// By default uses the estimate mode of `CONSERVATIVE` which is the
40    /// default in Bitcoin Core v27.
41    fn estimate_smart_fee(
42        &self,
43        conf_target: u16,
44    ) -> impl Future<Output = ClientResult<u64>> + Send;
45
46    /// Gets a [`Header`] with the given hash.
47    fn get_block_header(
48        &self,
49        hash: &BlockHash,
50    ) -> impl Future<Output = ClientResult<Header>> + Send;
51
52    /// Gets a [`Block`] with the given hash.
53    fn get_block(&self, hash: &BlockHash) -> impl Future<Output = ClientResult<Block>> + Send;
54
55    /// Gets a block height with the given hash.
56    fn get_block_height(&self, hash: &BlockHash) -> impl Future<Output = ClientResult<u64>> + Send;
57
58    /// Gets a [`Header`] at given height.
59    fn get_block_header_at(&self, height: u64)
60        -> impl Future<Output = ClientResult<Header>> + Send;
61
62    /// Gets a [`Block`] at given height.
63    fn get_block_at(&self, height: u64) -> impl Future<Output = ClientResult<Block>> + Send;
64
65    /// Gets the height of the most-work fully-validated chain.
66    ///
67    /// # Note
68    ///
69    /// The genesis block has a height of 0.
70    fn get_block_count(&self) -> impl Future<Output = ClientResult<u64>> + Send;
71
72    /// Gets the [`BlockHash`] at given height.
73    fn get_block_hash(&self, height: u64) -> impl Future<Output = ClientResult<BlockHash>> + Send;
74
75    /// Gets various state info regarding blockchain processing.
76    fn get_blockchain_info(&self) -> impl Future<Output = ClientResult<GetBlockchainInfo>> + Send;
77
78    /// Gets the timestamp in the block header of the current best block in bitcoin.
79    ///
80    /// # Note
81    ///
82    /// Time is Unix epoch time in seconds.
83    fn get_current_timestamp(&self) -> impl Future<Output = ClientResult<u32>> + Send;
84
85    /// Gets all transaction ids in mempool.
86    fn get_raw_mempool(&self) -> impl Future<Output = ClientResult<Vec<Txid>>> + Send;
87
88    /// Gets a raw transaction by its [`Txid`].
89    fn get_raw_transaction_verbosity_zero(
90        &self,
91        txid: &Txid,
92    ) -> impl Future<Output = ClientResult<GetRawTransactionVerbosityZero>> + Send;
93
94    /// Gets a raw transaction by its [`Txid`].
95    fn get_raw_transaction_verbosity_one(
96        &self,
97        txid: &Txid,
98    ) -> impl Future<Output = ClientResult<GetRawTransactionVerbosityOne>> + Send;
99
100    /// Returns details about an unspent transaction output.
101    fn get_tx_out(
102        &self,
103        txid: &Txid,
104        vout: u32,
105        include_mempool: bool,
106    ) -> impl Future<Output = ClientResult<GetTxOut>> + Send;
107
108    /// Gets the underlying [`Network`] information.
109    fn network(&self) -> impl Future<Output = ClientResult<Network>> + Send;
110}
111
112/// Broadcasting functionality that any Bitcoin client that interacts with the
113/// Bitcoin network should provide.
114///
115/// # Note
116///
117/// This is a fully `async` trait. The user should be responsible for
118/// handling the `async` nature of the trait methods. And if implementing
119/// this trait for a specific type that is not `async`, the user should
120/// consider wrapping with [`tokio`](https://tokio.rs)'s
121/// [`spawn_blocking`](https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html)
122/// or any other method.
123pub trait Broadcaster {
124    /// Sends a raw transaction to the network.
125    ///
126    /// # Parameters
127    ///
128    /// - `tx`: The raw transaction to send. This should be a byte array containing the serialized
129    ///   raw transaction data.
130    fn send_raw_transaction(
131        &self,
132        tx: &Transaction,
133    ) -> impl Future<Output = ClientResult<Txid>> + Send;
134
135    /// Tests if a raw transaction is valid.
136    fn test_mempool_accept(
137        &self,
138        tx: &Transaction,
139    ) -> impl Future<Output = ClientResult<Vec<TestMempoolAccept>>> + Send;
140
141    /// Submit a package of raw transactions (serialized, hex-encoded) to local node.
142    ///
143    /// The package will be validated according to consensus and mempool policy rules. If any
144    /// transaction passes, it will be accepted to mempool. This RPC is experimental and the
145    /// interface may be unstable. Refer to doc/policy/packages.md for documentation on package
146    /// policies.
147    ///
148    /// # Warning
149    ///
150    /// Successful submission does not mean the transactions will propagate throughout the network.
151    fn submit_package(
152        &self,
153        txs: &[Transaction],
154    ) -> impl Future<Output = ClientResult<SubmitPackage>> + Send;
155}
156
157/// Wallet functionality that any Bitcoin client **without private keys** that
158/// interacts with the Bitcoin network should provide.
159///
160/// For signing transactions, see [`Signer`].
161///
162/// # Note
163///
164/// This is a fully `async` trait. The user should be responsible for
165/// handling the `async` nature of the trait methods. And if implementing
166/// this trait for a specific type that is not `async`, the user should
167/// consider wrapping with [`tokio`](https://tokio.rs)'s
168/// [`spawn_blocking`](https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html)
169/// or any other method.
170pub trait Wallet {
171    /// Generates new address under own control for the underlying Bitcoin
172    /// client's wallet.
173    fn get_new_address(&self) -> impl Future<Output = ClientResult<Address>> + Send;
174
175    /// Gets information related to a transaction.
176    ///
177    /// # Note
178    ///
179    /// This assumes that the transaction is present in the underlying Bitcoin
180    /// client's wallet.
181    fn get_transaction(
182        &self,
183        txid: &Txid,
184    ) -> impl Future<Output = ClientResult<GetTransaction>> + Send;
185
186    /// Gets all Unspent Transaction Outputs (UTXOs) for the underlying Bitcoin
187    /// client's wallet.
188    fn get_utxos(&self) -> impl Future<Output = ClientResult<Vec<ListUnspent>>> + Send;
189
190    /// Lists transactions in the underlying Bitcoin client's wallet.
191    ///
192    /// # Parameters
193    ///
194    /// - `count`: The number of transactions to list. If `None`, assumes a maximum of 10
195    ///   transactions.
196    fn list_transactions(
197        &self,
198        count: Option<usize>,
199    ) -> impl Future<Output = ClientResult<Vec<ListTransactions>>> + Send;
200
201    /// Lists all wallets in the underlying Bitcoin client.
202    fn list_wallets(&self) -> impl Future<Output = ClientResult<Vec<String>>> + Send;
203
204    /// Creates a raw transaction.
205    fn create_raw_transaction(
206        &self,
207        raw_tx: CreateRawTransaction,
208    ) -> impl Future<Output = ClientResult<Transaction>> + Send;
209}
210
211/// Signing functionality that any Bitcoin client **with private keys** that
212/// interacts with the Bitcoin network should provide.
213///
214/// # Note
215///
216/// This is a fully `async` trait. The user should be responsible for
217/// handling the `async` nature of the trait methods. And if implementing
218/// this trait for a specific type that is not `async`, the user should
219/// consider wrapping with [`tokio`](https://tokio.rs)'s
220/// [`spawn_blocking`](https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html)
221/// or any other method.
222pub trait Signer {
223    /// Signs a transaction using the keys available in the underlying Bitcoin
224    /// client's wallet and returns a signed transaction.
225    ///
226    /// # Note
227    ///
228    /// The returned signed transaction might not be consensus-valid if it
229    /// requires additional signatures, such as in a multisignature context.
230    fn sign_raw_transaction_with_wallet(
231        &self,
232        tx: &Transaction,
233        prev_outputs: Option<Vec<PreviousTransactionOutput>>,
234    ) -> impl Future<Output = ClientResult<SignRawTransactionWithWallet>> + Send;
235
236    /// Gets the underlying [`Xpriv`] from the wallet.
237    fn get_xpriv(&self) -> impl Future<Output = ClientResult<Option<Xpriv>>> + Send;
238
239    /// Imports the descriptors into the wallet.
240    fn import_descriptors(
241        &self,
242        descriptors: Vec<ImportDescriptor>,
243        wallet_name: String,
244    ) -> impl Future<Output = ClientResult<Vec<ImportDescriptorResult>>> + Send;
245}