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, GetMempoolInfo, 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 /// Returns details on the active state of the mempool.
89 fn get_mempool_info(&self) -> impl Future<Output = ClientResult<GetMempoolInfo>> + Send;
90
91 /// Gets a raw transaction by its [`Txid`].
92 fn get_raw_transaction_verbosity_zero(
93 &self,
94 txid: &Txid,
95 ) -> impl Future<Output = ClientResult<GetRawTransactionVerbosityZero>> + Send;
96
97 /// Gets a raw transaction by its [`Txid`].
98 fn get_raw_transaction_verbosity_one(
99 &self,
100 txid: &Txid,
101 ) -> impl Future<Output = ClientResult<GetRawTransactionVerbosityOne>> + Send;
102
103 /// Returns details about an unspent transaction output.
104 fn get_tx_out(
105 &self,
106 txid: &Txid,
107 vout: u32,
108 include_mempool: bool,
109 ) -> impl Future<Output = ClientResult<GetTxOut>> + Send;
110
111 /// Gets the underlying [`Network`] information.
112 fn network(&self) -> impl Future<Output = ClientResult<Network>> + Send;
113}
114
115/// Broadcasting functionality that any Bitcoin client that interacts with the
116/// Bitcoin network should provide.
117///
118/// # Note
119///
120/// This is a fully `async` trait. The user should be responsible for
121/// handling the `async` nature of the trait methods. And if implementing
122/// this trait for a specific type that is not `async`, the user should
123/// consider wrapping with [`tokio`](https://tokio.rs)'s
124/// [`spawn_blocking`](https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html)
125/// or any other method.
126pub trait Broadcaster {
127 /// Sends a raw transaction to the network.
128 ///
129 /// # Parameters
130 ///
131 /// - `tx`: The raw transaction to send. This should be a byte array containing the serialized
132 /// raw transaction data.
133 fn send_raw_transaction(
134 &self,
135 tx: &Transaction,
136 ) -> impl Future<Output = ClientResult<Txid>> + Send;
137
138 /// Tests if a raw transaction is valid.
139 fn test_mempool_accept(
140 &self,
141 tx: &Transaction,
142 ) -> impl Future<Output = ClientResult<Vec<TestMempoolAccept>>> + Send;
143
144 /// Submit a package of raw transactions (serialized, hex-encoded) to local node.
145 ///
146 /// The package will be validated according to consensus and mempool policy rules. If any
147 /// transaction passes, it will be accepted to mempool. This RPC is experimental and the
148 /// interface may be unstable. Refer to doc/policy/packages.md for documentation on package
149 /// policies.
150 ///
151 /// # Warning
152 ///
153 /// Successful submission does not mean the transactions will propagate throughout the network.
154 fn submit_package(
155 &self,
156 txs: &[Transaction],
157 ) -> impl Future<Output = ClientResult<SubmitPackage>> + Send;
158}
159
160/// Wallet functionality that any Bitcoin client **without private keys** that
161/// interacts with the Bitcoin network should provide.
162///
163/// For signing transactions, see [`Signer`].
164///
165/// # Note
166///
167/// This is a fully `async` trait. The user should be responsible for
168/// handling the `async` nature of the trait methods. And if implementing
169/// this trait for a specific type that is not `async`, the user should
170/// consider wrapping with [`tokio`](https://tokio.rs)'s
171/// [`spawn_blocking`](https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html)
172/// or any other method.
173pub trait Wallet {
174 /// Generates new address under own control for the underlying Bitcoin
175 /// client's wallet.
176 fn get_new_address(&self) -> impl Future<Output = ClientResult<Address>> + Send;
177
178 /// Gets information related to a transaction.
179 ///
180 /// # Note
181 ///
182 /// This assumes that the transaction is present in the underlying Bitcoin
183 /// client's wallet.
184 fn get_transaction(
185 &self,
186 txid: &Txid,
187 ) -> impl Future<Output = ClientResult<GetTransaction>> + Send;
188
189 /// Gets all Unspent Transaction Outputs (UTXOs) for the underlying Bitcoin
190 /// client's wallet.
191 fn get_utxos(&self) -> impl Future<Output = ClientResult<Vec<ListUnspent>>> + Send;
192
193 /// Lists transactions in the underlying Bitcoin client's wallet.
194 ///
195 /// # Parameters
196 ///
197 /// - `count`: The number of transactions to list. If `None`, assumes a maximum of 10
198 /// transactions.
199 fn list_transactions(
200 &self,
201 count: Option<usize>,
202 ) -> impl Future<Output = ClientResult<Vec<ListTransactions>>> + Send;
203
204 /// Lists all wallets in the underlying Bitcoin client.
205 fn list_wallets(&self) -> impl Future<Output = ClientResult<Vec<String>>> + Send;
206
207 /// Creates a raw transaction.
208 fn create_raw_transaction(
209 &self,
210 raw_tx: CreateRawTransaction,
211 ) -> impl Future<Output = ClientResult<Transaction>> + Send;
212}
213
214/// Signing functionality that any Bitcoin client **with private keys** that
215/// interacts with the Bitcoin network should provide.
216///
217/// # Note
218///
219/// This is a fully `async` trait. The user should be responsible for
220/// handling the `async` nature of the trait methods. And if implementing
221/// this trait for a specific type that is not `async`, the user should
222/// consider wrapping with [`tokio`](https://tokio.rs)'s
223/// [`spawn_blocking`](https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html)
224/// or any other method.
225pub trait Signer {
226 /// Signs a transaction using the keys available in the underlying Bitcoin
227 /// client's wallet and returns a signed transaction.
228 ///
229 /// # Note
230 ///
231 /// The returned signed transaction might not be consensus-valid if it
232 /// requires additional signatures, such as in a multisignature context.
233 fn sign_raw_transaction_with_wallet(
234 &self,
235 tx: &Transaction,
236 prev_outputs: Option<Vec<PreviousTransactionOutput>>,
237 ) -> impl Future<Output = ClientResult<SignRawTransactionWithWallet>> + Send;
238
239 /// Gets the underlying [`Xpriv`] from the wallet.
240 fn get_xpriv(&self) -> impl Future<Output = ClientResult<Option<Xpriv>>> + Send;
241
242 /// Imports the descriptors into the wallet.
243 fn import_descriptors(
244 &self,
245 descriptors: Vec<ImportDescriptor>,
246 wallet_name: String,
247 ) -> impl Future<Output = ClientResult<Vec<ImportDescriptorResult>>> + Send;
248}