corepc_types/v19/blockchain/
mod.rs

1// SPDX-License-Identifier: CC0-1.0
2
3//! The JSON-RPC API for Bitcoin Core `v0.19` - blockchain.
4//!
5//! Types for methods found under the `== Blockchain ==` section of the API docs.
6
7mod error;
8mod into;
9
10use alloc::collections::BTreeMap;
11
12use serde::{Deserialize, Serialize};
13
14// TODO: Remove wildcard, use explicit types.
15pub use self::error::*;
16use super::{GetChainTxStatsError, GetMempoolInfoError};
17
18/// Result of JSON-RPC method `getblockchaininfo`.
19///
20/// > getblockchaininfo
21/// >
22/// > Returns an object containing various state info regarding blockchain processing.
23#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
24#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
25pub struct GetBlockchainInfo {
26    /// Current network name as defined in BIP70 (main, test, signet, regtest).
27    pub chain: String,
28    /// The current number of blocks processed in the server.
29    pub blocks: i64,
30    /// The current number of headers we have validated.
31    pub headers: i64,
32    /// The hash of the currently best block.
33    #[serde(rename = "bestblockhash")]
34    pub best_block_hash: String,
35    /// The current difficulty.
36    pub difficulty: f64,
37    /// Median time for the current best block.
38    #[serde(rename = "mediantime")]
39    pub median_time: i64,
40    /// Estimate of verification progress (between 0 and 1).
41    #[serde(rename = "verificationprogress")]
42    pub verification_progress: f64,
43    /// Estimate of whether this node is in Initial Block Download (IBD) mode.
44    #[serde(rename = "initialblockdownload")]
45    pub initial_block_download: bool,
46    /// Total amount of work in active chain, in hexadecimal.
47    #[serde(rename = "chainwork")]
48    pub chain_work: String,
49    /// The estimated size of the block and undo files on disk.
50    pub size_on_disk: u64,
51    /// If the blocks are subject to pruning.
52    pub pruned: bool,
53    /// Lowest-height complete block stored (only present if pruning is enabled).
54    #[serde(rename = "pruneheight")]
55    pub prune_height: Option<i64>,
56    /// Whether automatic pruning is enabled (only present if pruning is enabled).
57    pub automatic_pruning: Option<bool>,
58    /// The target size used by pruning (only present if automatic pruning is enabled).
59    pub prune_target_size: Option<i64>,
60    /// Status of softforks in progress, maps softfork name -> [`Softfork`].
61    #[serde(default)]
62    pub softforks: BTreeMap<String, Softfork>,
63    /// Any network and blockchain warnings.
64    pub warnings: String,
65}
66
67/// Softfork status. Part of `getblockchaininfo`.
68#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
69#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
70pub struct Softfork {
71    /// The [`SoftforkType`]: one of "buried", "bip9".
72    #[serde(rename = "type")]
73    pub type_: SoftforkType,
74    /// The status of bip9 softforks (only for "bip9" type).
75    pub bip9: Option<Bip9SoftforkInfo>,
76    ///  Height of the first block which the rules are or will be enforced (only for "buried" type, or "bip9" type with "active" status).
77    pub height: Option<i64>,
78    /// `true` if the rules are enforced for the mempool and the next block.
79    pub active: bool,
80}
81
82/// The softfork type. Part of `getblockchaininfo`.
83#[derive(Copy, Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
84#[serde(rename_all = "lowercase")]
85pub enum SoftforkType {
86    /// Softfork is "buried" (as defined in [BIP-90]).
87    ///
88    /// [BIP-90] <https://github.com/bitcoin/bips/blob/master/bip-0090.mediawiki>
89    Buried,
90    /// Softfork is "bip9" (see [BIP-9]).
91    ///
92    /// [BIP-9] <https://github.com/bitcoin/bips/blob/master/bip-0009.mediawiki>
93    Bip9,
94}
95
96/// BIP-9 softfork info. Part of `getblockchaininfo`.
97#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
98#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
99pub struct Bip9SoftforkInfo {
100    /// One of "defined", "started", "locked_in", "active", "failed".
101    pub status: Bip9SoftforkStatus,
102    /// The bit (0-28) in the block version field used to signal this softfork (only for "started" status).
103    pub bit: Option<u8>,
104    /// The minimum median time past of a block at which the bit gains its meaning.
105    pub start_time: i64,
106    /// The median time past of a block at which the deployment is considered failed if not yet locked in.
107    pub timeout: i64,
108    /// Height of the first block to which the status applies.
109    pub since: i64,
110    /// Numeric statistics about BIP-9 signalling for a softfork (only for "started" status).
111    pub statistics: Option<Bip9SoftforkStatistics>,
112}
113
114/// BIP-9 softfork status. Part of `getblockchaininfo`.
115#[derive(Copy, Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
116#[serde(rename_all = "snake_case")]
117pub enum Bip9SoftforkStatus {
118    /// BIP-9 softfork status "defined".
119    Defined,
120    /// BIP-9 softfork status "started".
121    Started,
122    /// BIP-9 softfork status "locked_in".
123    LockedIn,
124    /// BIP-9 softfork status "active".
125    Active,
126    /// BIP-9 softfork status "failed".
127    Failed,
128}
129
130/// BIP-9 softfork statistics. Part of `getblockchaininfo`.
131#[derive(Clone, PartialEq, Eq, Debug, Deserialize, Serialize)]
132#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
133pub struct Bip9SoftforkStatistics {
134    /// The length in blocks of the BIP9 signalling period.
135    pub period: i64,
136    /// The number of blocks with the version bit set required to activate the feature.
137    pub threshold: Option<i64>,
138    /// The number of blocks elapsed since the beginning of the current period.
139    pub elapsed: i64,
140    /// The number of blocks with the version bit set in the current period.
141    pub count: i64,
142    /// `false` if there are not enough blocks left in this period to pass activation threshold.
143    pub possible: Option<bool>,
144}
145
146/// Result of JSON-RPC method `getblockfilter`.
147///
148/// > getblockfilter "blockhash" ( "filtertype" )
149/// >
150/// > Retrieve a BIP 157 content filter for a particular block.
151/// >
152/// > Arguments:
153/// > 1. blockhash     (string, required) The hash of the block
154/// > 2. filtertype    (string, optional, default=basic) The type name of the filter
155#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
156#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
157pub struct GetBlockFilter {
158    /// The hex-encoded filter data.
159    pub filter: String,
160    /// The hex-encoded filter header.
161    pub header: String,
162}
163
164/// Result of JSON-RPC method `getchaintxstats`.
165///
166/// > getchaintxstats ( nblocks blockhash )
167/// >
168/// > Compute statistics about the total number and rate of transactions in the chain.
169#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
170#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
171pub struct GetChainTxStats {
172    /// The timestamp for the final block in the window in UNIX format.
173    pub time: i64,
174    /// The total number of transactions in the chain up to that point.
175    #[serde(rename = "txcount")]
176    pub tx_count: i64,
177    /// The hash of the final block in the window.
178    pub window_final_block_hash: String,
179    /// The height of the final block in the window.
180    pub window_final_block_height: i64,
181    /// Size of the window in number of blocks.
182    pub window_block_count: i64,
183    /// The number of transactions in the window. Only returned if "window_block_count" is > 0.
184    pub window_tx_count: Option<i64>,
185    /// The elapsed time in the window in seconds. Only returned if "window_block_count" is > 0.
186    pub window_interval: Option<i64>,
187    /// The average rate of transactions per second in the window. Only returned if "window_interval" is > 0.
188    #[serde(rename = "txrate")]
189    pub tx_rate: Option<i64>,
190}
191
192/// Result of JSON-RPC method `getmempoolancestors` with verbose set to `false`.
193///
194/// > getmempoolancestors txid (verbose)
195/// >
196/// > If txid is in the mempool, returns all in-mempool ancestors.
197/// >
198/// > Arguments:
199/// > 1. "txid"                 (string, required) The transaction id (must be in mempool)
200#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
201#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
202pub struct GetMempoolAncestors(pub Vec<String>);
203
204/// Result of JSON-RPC method `getmempoolancestors` with verbose set to true.
205///
206/// Map of txid to `MempoolEntry` i.e., an ancestor.
207#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
208#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
209pub struct GetMempoolAncestorsVerbose(pub BTreeMap<String, MempoolEntry>);
210
211/// Result of JSON-RPC method `getmempooldescendants` with verbose set to `false`.
212///
213/// > getmempooldescendants txid (verbose)
214/// >
215/// > If txid is in the mempool, returns all in-mempool descendants.
216/// >
217/// > Arguments:
218/// > 1. "txid"                 (string, required) The transaction id (must be in mempool)
219#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
220#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
221pub struct GetMempoolDescendants(pub Vec<String>);
222
223/// Result of JSON-RPC method `getmempooldescendants` with verbose set to true.
224///
225/// Map of txid to [`MempoolEntry`] i.e., a descendant.
226#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
227#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
228pub struct GetMempoolDescendantsVerbose(pub BTreeMap<String, MempoolEntry>);
229
230/// Result of JSON-RPC method `getmempoolentry`.
231///
232/// > getmempoolentry txid
233/// >
234/// > Returns mempool data for given transaction
235/// >
236/// > Arguments:
237/// > 1. "txid"                 (string, required) The transaction id (must be in mempool)
238#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
239#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
240pub struct GetMempoolEntry(pub MempoolEntry);
241
242/// Mempool data. Part of `getmempoolentry`.
243#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
244#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
245pub struct MempoolEntry {
246    /// Virtual transaction size as defined in BIP 141.
247    ///
248    /// This is different from actual serialized size for witness transactions as witness data is discounted.  v0.19 and later only.
249    pub vsize: i64,
250    /// DEPRECATED: same as vsize. Only returned if bitcoind is started with -deprecatedrpc=size
251    /// size will be completely removed in v0.20.
252    pub size: Option<i64>,
253    /// Transaction weight as defined in BIP 141.
254    pub weight: i64,
255    /// DEPRECATED: Transaction fee in BTC.
256    pub fee: f64,
257    /// DEPRECATED: Transaction fee with fee deltas used for mining priority.
258    #[serde(rename = "modifiedfee")]
259    pub modified_fee: f64,
260    /// Local time transaction entered pool in seconds since 1 Jan 1970 GMT.
261    pub time: i64,
262    /// Block height when transaction entered pool.
263    pub height: i64,
264    /// Number of in-mempool descendant transactions (including this one).
265    #[serde(rename = "descendantcount")]
266    pub descendant_count: i64,
267    /// Virtual transaction size of in-mempool descendants (including this one).
268    #[serde(rename = "descendantsize")]
269    pub descendant_size: i64,
270    /// DEPRECATED: Modified fees (see above) of in-mempool descendants (including this one).
271    #[serde(rename = "descendantfees")]
272    pub descendant_fees: f64,
273    /// Number of in-mempool ancestor transactions (including this one).
274    #[serde(rename = "ancestorcount")]
275    pub ancestor_count: i64,
276    /// Virtual transaction size of in-mempool ancestors (including this one).
277    #[serde(rename = "ancestorsize")]
278    pub ancestor_size: i64,
279    /// DEPRECATED: Modified fees (see above) of in-mempool ancestors (including this one).
280    #[serde(rename = "ancestorfees")]
281    pub ancestor_fees: f64,
282    /// Hash of serialized transaction, including witness data.
283    pub wtxid: String,
284    /// Fee object which contains the base fee, modified fee (with fee deltas), and
285    /// ancestor/descendant fee totals all in BTC.
286    pub fees: MempoolEntryFees,
287    /// Unconfirmed transactions used as inputs for this transaction (parent transaction id).
288    pub depends: Vec<String>,
289    /// Unconfirmed transactions spending outputs from this transaction (child transaction id).
290    #[serde(rename = "spentby")]
291    pub spent_by: Vec<String>,
292    /// Whether this transaction could be replaced due to BIP125 (replace-by-fee)
293    #[serde(rename = "bip125-replaceable")]
294    pub bip125_replaceable: bool,
295}
296
297/// Fee object. Part of `getmempoolentry`.
298///
299/// Contains the base fee, modified fee (with fee deltas), and ancestor/descendant fee totals,
300/// all in BTC.
301#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
302#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
303pub struct MempoolEntryFees {
304    /// Transaction fee in BTC.
305    pub base: f64,
306    /// Transaction fee with fee deltas used for mining priority in BTC.
307    pub modified: f64,
308    /// Modified fees (see above) of in-mempool ancestors (including this one) in BTC
309    pub ancestor: f64,
310    /// Modified fees (see above) of in-mempool descendants (including this one) in BTC.
311    pub descendant: f64,
312}
313
314/// Result of JSON-RPC method `getmempoolinfo` with verbose set to `true`.
315///
316/// > getmempoolinfo
317/// >
318/// > Returns details on the active state of the TX memory pool.
319#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
320#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
321pub struct GetMempoolInfo {
322    /// True if the mempool is fully loaded. v0.19 and later only.
323    pub loaded: bool,
324    /// Current transaction count.
325    pub size: i64,
326    /// Sum of all virtual transaction sizes as defined in BIP 141.
327    ///
328    /// Differs from actual serialized size because witness data is discounted.
329    pub bytes: i64,
330    /// Total memory usage for the mempool.
331    pub usage: i64,
332    /// Maximum memory usage for the mempool.
333    #[serde(rename = "maxmempool")]
334    pub max_mempool: i64,
335    /// Minimum fee rate in BTC/kB for a transaction to be accepted.
336    ///
337    /// This is the maximum of `minrelaytxfee` and the minimum mempool fee.
338    #[serde(rename = "mempoolminfee")]
339    pub mempool_min_fee: f64,
340    /// Current minimum relay fee for transactions.
341    #[serde(rename = "minrelaytxfee")]
342    pub min_relay_tx_fee: f64,
343}
corepc_types/v19/blockchain/mod.rs

corepc_types/v19/blockchain/
mod.rs
