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}