Struct Query 

pub struct Query(/* private fields */);

Implementations

impl Query

pub fn addr_last_activity_height( &self, addr: &Addr, before_txid: Option<&Txid>, ) -> Result<Height>

Height of the last on-chain activity for an address (last tx_index to height). With before_txid, returns the newest activity strictly older than that cursor. Used by paginated chain etags so a new tx above the cursor doesn’t invalidate deeper pages.

impl Query

pub fn addr_hash_prefix_matches( &self, addr_type: OutputType, prefix: &str, ) -> Result<AddrHashPrefixMatches>

impl Query

pub fn addr_mempool_hash(&self, addr: &Addr) -> Option<u64>

pub fn addr_mempool_txs( &self, addr: &Addr, limit: usize, ) -> Result<Vec<Transaction>>

impl Query

pub fn addr(&self, addr: Addr) -> Result<AddrStats>

impl Query

pub fn addr_txs_chain( &self, addr: &Addr, after_txid: Option<Txid>, limit: usize, ) -> Result<Vec<Transaction>>

pub fn addr_txids( &self, addr: Addr, after_txid: Option<Txid>, limit: usize, ) -> Result<Vec<Txid>>

impl Query

pub fn addr_utxos(&self, addr: Addr, max_utxos: usize) -> Result<Vec<Utxo>>

impl Query

pub fn block(&self, hash: &BlockHash) -> Result<BlockInfo>

Block by hash. Unknown hash → 404 via height_by_hash.

pub fn block_by_height(&self, height: Height) -> Result<BlockInfo>

Block by height. Height past tip (or pre-genesis) → OutOfRange.

pub fn block_by_height_v1(&self, height: Height) -> Result<BlockInfoV1>

V1 block by height. Ceiling is min(indexed, computed) because blocks_v1_range reads computer-stamped series (pools, fees, supply state). Anything past computed_height would short-read.

pub fn block_header_hex(&self, hash: &BlockHash) -> Result<String>

Hex-encoded 80-byte block header. Decode-then-encode roundtrip doubles as a corruption check on the on-disk bytes.

pub fn block_hash_by_height(&self, height: Height) -> Result<BlockHash>

Block hash by height. Cheap typed-index read with a semantic bounds gate (OutOfRange for past-tip, Internal if the data is unexpectedly missing inside the gate).

pub fn blocks( &self, start_height: Option<Height>, count: u32, ) -> Result<Vec<BlockInfo>>

Most recent count blocks ending at start_height (default tip), returned in descending-height order.

pub fn blocks_v1( &self, start_height: Option<Height>, count: u32, ) -> Result<Vec<BlockInfoV1>>

V1 most recent count blocks with extras ending at start_height (default tip), returned in descending-height order.

pub fn height_by_hash(&self, hash: &BlockHash) -> Result<Height>

Hash to height, clamped to the safe-lengths snapshot. The prefix store keys on the first 8 bytes of the hash, so the resolved height is verified against the full blockhash[height] before being returned. Prefix collisions, unknown hashes, and hashes past the snapshot all surface as NotFound.

pub fn read_block_header(&self, height: Height) -> Result<Header>

Read the on-disk 80-byte header at height and decode it. Caller must bounds-check height (no OutOfRange mapping here). Returns bitcoin::block::Header because callers feed it into upstream consensus-encoding APIs (serialize_hex, MerkleBlock).

impl Query

pub fn block_raw(&self, hash: &BlockHash) -> Result<Vec<u8>>

impl Query

pub fn block_status(&self, hash: &BlockHash) -> Result<BlockStatus>

impl Query

pub fn block_by_timestamp(&self, timestamp: Timestamp) -> Result<BlockTimestamp>

Most recent block with timestamp ≤ ts. Backs mempool.space’s GET /api/v1/mining/blocks/timestamp/{ts}. Future timestamps return the chain tip; pre-genesis timestamps return 404.

Uses day1.first_height for an O(1) seek to the target date, then a linear scan bounded by the BIP113 MTP rule (see MTP_TERMINAL_STREAK). Symmetric backward scan handles targets earlier than the seeded day’s first block.

impl Query

pub fn block_txids(&self, hash: &BlockHash) -> Result<Vec<Txid>>

All txids in the block, canonical order (coinbase first). NotFound if the hash is unknown (or only collides on the 8-byte prefix), OutOfRange if the resolved height is past the indexed tip. Unpaginated by design.

pub fn block_txs( &self, hash: &BlockHash, start_index: BlockTxIndex, count: u32, ) -> Result<Vec<Transaction>>

Up to count transactions from the block, starting at the in-block offset start_index (0 = coinbase). OutOfRange when start_index is past the last tx in the block. Caller (route layer) sets count.

pub fn block_txid_at_index( &self, hash: &BlockHash, index: BlockTxIndex, ) -> Result<Txid>

Txid at an in-block offset (index is the position within the block, 0 = coinbase). NotFound if the hash is unknown or only collides on the 8-byte prefix; OutOfRange if index is past the last tx in the block.

pub fn transactions_by_indices( &self, indices: &[TxIndex], ) -> Result<Vec<Transaction>>

Batch-read transactions at arbitrary indices. Reads in ascending index order for I/O locality, returns in caller’s order.

Three-phase approach for sequential cursor I/O: Phase 1: decode transactions, collect outpoints + per-input prevout metadata (sorted by tx_index). Phase 2: resolve each prevout’s script_pubkey (sorted by output_type, then type_index, for sequential addr-vec reads). Phase 3: assemble Transaction objects, compute fees.

The final unwrap is provably safe: order is a permutation of 0..len, Phase 1 produces exactly one DecodedTx per position, and Phase 3 assigns each txs[pos] once before the collect.

impl Query

pub fn cpfp(&self, txid: &Txid) -> Result<CpfpInfo>

Returns live mempool information when available, otherwise reconstructs the confirmed same-block cluster from indexed data.

pub fn effective_fee_rate(&self, txid: &Txid) -> Result<FeeRate>

Effective SFL chunk rate for live, confirmed, or replaced transactions.

impl Query

pub fn mempool_info(&self) -> Result<MempoolInfo>

pub fn mempool_txids(&self) -> Result<Vec<Txid>>

pub fn recommended_fees(&self) -> Result<RecommendedFees>

pub fn mempool_blocks(&self) -> Result<Vec<MempoolBlock>>

pub fn indexer_prevout_resolver( &self, ) -> Box<dyn Fn(&[(Txid, Vout)]) -> FxHashMap<(Txid, Vout), TxOut> + Send + Sync>

Indexer-backed resolver for confirmed-parent prevouts. Boxed so the caller (typically Mempool::start_with) can stash one resolver behind a stable type for the lifetime of the loop.

pub fn mempool_recent(&self) -> Result<Vec<MempoolRecentTx>>

pub fn tx_rbf(&self, txid: &Txid) -> Result<RbfResponse>

RBF history for a tx. Matches mempool.space’s GET /api/v1/tx/:txid/rbf. Mempool builds the owned tree under one read-lock window; this then layers on mined + effective fee rate from the indexer/computer.

pub fn recent_replacements( &self, full_rbf_only: bool, ) -> Result<Vec<ReplacementNode>>

Recent RBF replacements. Matches mempool.space’s GET /api/v1/replacements and GET /api/v1/fullrbf/replacements. Most-recent first, capped at 25. full_rbf_only keeps only trees with at least one non-signaling predecessor.

pub fn transaction_times(&self, txids: &[Txid]) -> Result<Vec<u64>>

first_seen Unix-second timestamps. Matches mempool.space’s POST /api/v1/transaction-times. Returns 0 for unknowns.

pub fn mempool_hash(&self) -> Result<NextBlockHash>

Content hash of the projected next block. Same value as the mempool ETag. Polling lets monitors detect a stalled sync.

pub fn block_template(&self) -> Result<BlockTemplate>

Full projected next block (Core’s getblocktemplate selection) with stats and full tx bodies in GBT order.

pub fn block_template_diff( &self, since: NextBlockHash, ) -> Result<BlockTemplateDiff>

Delta of the projected next block since since. NotFound when since has aged out (client should fall back to block_template).

impl Query

pub fn block_fee_rates( &self, time_period: TimePeriod, ) -> Result<Vec<BlockFeeRatesEntry>>

Time-bucketed fee-rate percentiles over time_period. One entry per bucket, ordered chronologically. Each entry carries the bucket’s average height/timestamp and the seven percentile means (min, pct10, pct25, median, pct75, pct90, max).

impl Query

pub fn block_fees(&self, time_period: TimePeriod) -> Result<Vec<BlockFeesEntry>>

Time-bucketed average block fees over time_period. One entry per bucket, ordered chronologically. Each entry carries the bucket’s average height/timestamp, the round-half-up mean of block fees in sats, and the bucket-mean USD spot price (the spot price, not fees-in-USD: clients multiply).

impl Query

pub fn block_rewards( &self, time_period: TimePeriod, ) -> Result<Vec<BlockRewardsEntry>>

Time-bucketed average block rewards (subsidy + fees) over time_period. One entry per bucket, ordered chronologically. Each entry carries the bucket’s average height/timestamp, the round-half-up mean of coinbase rewards in sats, and the bucket-mean USD spot price (the spot price, not rewards-in-USD: clients multiply).

impl Query

pub fn block_sizes_weights( &self, time_period: TimePeriod, ) -> Result<BlockSizesWeights>

Time-bucketed average block size and weight over time_period. Returns two parallel vecs (one entry per bucket, ordered chronologically): byte size in sizes, weight units in weights. Each entry carries the bucket’s average height/timestamp and the round-half-up mean of the corresponding metric. Single bucket-pass: built via .map(...).unzip() to avoid re-walking buckets.

impl Query

pub fn difficulty_adjustment(&self) -> Result<DifficultyAdjustment>

Live difficulty-adjustment snapshot for the current epoch. Bundles progress through the 2016-block window, the projected next-retarget percentage from observed pace, an estimated wall-clock retarget time, remaining blocks/time, the previous retarget percentage (current epoch vs previous epoch first-block difficulty), and the time offset from a 600s/block schedule. Output time fields are in milliseconds.

impl Query

pub fn difficulty_adjustments( &self, time_period: Option<TimePeriod>, ) -> Result<Vec<DifficultyAdjustmentEntry>>

All difficulty adjustments (one entry per retarget) whose first block lies within time_period, in reverse chronological order (newest first). None walks every epoch from genesis. The window cutoff is wall-clock (via start_height) rather than block-count, so the returned set is “epochs whose first block lies within the period”, not “the last N epochs”.

impl Query

pub fn hashrate( &self, time_period: Option<TimePeriod>, max_points: usize, ) -> Result<HashrateSummary>

Network hashrate summary for time_period (None walks the full chain). Bundles a downsampled daily hashrate series (at most max_points samples; sampling step is total_days / max_points, floored at 1), every difficulty retarget within the window, the current 1-day hashrate, and the current block’s difficulty. The window cutoff is wall-clock (via start_height), matching difficulty_adjustments so the two endpoints agree on the same time_period.

impl Query

pub fn mining_pools(&self, time_period: TimePeriod) -> Result<PoolsSummary>

Mining-pool leaderboard for time_period. For each pool, computes block count over the window via cumulative(end) - cumulative(start - 1) (tip-cumulative minus pre-window-cumulative), sorts pools by count descending, assigns ranks, and emits the per-pool share. Also bundles current / 3d / 1w network hashrate snapshots. Returns zeros early when no blocks have been indexed. The window start uses the timestamp-based lookback vecs (_24h, _3d, …) rather than block-count math; TimePeriod::All walks from genesis.

pub fn all_pools(&self) -> Vec<PoolInfo>

All supported pools as PoolInfo. Static list, no indexer reads, can’t fail.

pub fn pool_detail(&self, slug: PoolSlug) -> Result<PoolDetail>

Per-pool detail: lifetime block count plus 24h and 1w windowed counts, each as a share of network blocks in the same window. The 24h share is also used to weight the current 1-day network hashrate into a per-pool estimated_hashrate. total_reward is Some only for major pools (minor pools don’t track per-pool reward sums); under stamp lag on a major pool’s reward vec this errors rather than silently reporting None.

pub fn pool_blocks( &self, slug: PoolSlug, before_height: Option<Height>, limit: usize, ) -> Result<Vec<BlockInfoV1>>

Page of blocks mined by slug, in descending height order, capped at limit. before_height is the inclusive upper bound to paginate from (defaults to tip). Returns an empty Vec if the pool has no recorded blocks. Heights come from a sorted-ascending per-pool index, so the page is computed via partition_point then reversed; consecutive runs are merged into a single bulk read of blocks_v1_range.

pub fn pool_hashrate(&self, slug: PoolSlug) -> Result<Vec<PoolHashrateEntry>>

Weekly-sampled hashrate series for a single pool over the full chain. Each point’s hashrate is network_hashrate(day) * pool_share_over_7d, where the share is the pool’s last-7-days block count divided by the network’s last-7-days block count.

pub fn pools_hashrate( &self, time_period: Option<TimePeriod>, ) -> Result<Vec<PoolHashrateEntry>>

Multi-pool weekly-sampled hashrate series over time_period. Walks the full chain when time_period is None or Some(TimePeriod::All). For each known pool, emits one entry per weekly sample where the hashrate is network_hashrate(day) * pool_share_over_7d, tagged with pool_name. Entries from all pools are concatenated; the chart layer groups by pool name.

impl Query

pub fn reward_stats(&self, block_count: usize) -> Result<RewardStats>

Sums coinbase rewards, fees, and tx counts over the last block_count blocks ending at the current tip. Errors OutOfRange if block_count is zero, and Internal if any of the three per-block vecs (coinbase, fees, tx count) is stamped short of the tip - silent truncation by fold_range_at would otherwise produce a quietly low total.

impl Query

pub fn live_price(&self) -> Result<Dollars>

pub fn live_payment_histogram(&self) -> Result<HistogramEmaCompact>

Smoothed payment output histogram at the live tip, quantized for the wire.

pub fn confirmed_payment_histogram( &self, height: usize, ) -> Result<HistogramEmaCompact>

Smoothed payment output histogram for a confirmed height, deterministically reconstructed by replaying the window ending at height. EMA values are seed-independent, so the result is exact.

pub fn confirmed_payment_histogram_day( &self, day: Day1, ) -> Result<HistogramEmaCompact>

Smoothed payment output histogram for a calendar day: the bin-by-bin average of every confirmed block’s per-block EMA. The first block in each EMA config segment is reconstructed exactly, then later blocks in the segment are walked sequentially. Averaging keeps the result an intensive per-block rate rather than letting a busy day dominate.

pub fn live_output_histogram(&self) -> Result<HistogramRaw>

Unfiltered per-bin output counts at the live tip: every forming-block mempool output binned by value, with none of the round-dollar payment filters applied. Zeros when no mempool is configured.

pub fn confirmed_output_histogram(&self, height: usize) -> Result<HistogramRaw>

Unfiltered per-bin output counts for a confirmed height: every output in the block binned by value, with no payment filtering.

pub fn confirmed_output_histogram_day(&self, day: Day1) -> Result<HistogramRaw>

Unfiltered per-bin output counts for a calendar day: every block’s output histogram summed bin-by-bin. Raw counts are additive, so the day total is just the sum across its confirmed blocks.

impl Query

pub fn historical_price( &self, timestamp: Option<Timestamp>, ) -> Result<HistoricalPrice>

impl Query

pub fn search_series(&self, query: &SearchQuery) -> Vec<&'static str>

pub fn series_not_found_error(&self, series: &SeriesName) -> Error

Returns the error for a missing series: SeriesUnsupportedIndex if the name exists at other indexes, else SeriesNotFound with fuzzy-match suggestions.

pub fn latest(&self, series: &SeriesName, index: Index) -> Result<Value>

Returns the latest value for a single series as a JSON value.

pub fn len(&self, series: &SeriesName, index: Index) -> Result<usize>

Returns the length (total data points) for a single series.

pub fn version(&self, series: &SeriesName, index: Index) -> Result<Version>

Returns the version for a single series.

pub fn search( &self, params: &SeriesSelection, ) -> Result<Vec<&'static dyn AnyExportableVec>>

Search for vecs matching the given series and index. Returns error if no series requested or any requested series is not found.

pub fn weight( vecs: &[&dyn AnyExportableVec], from: Option<i64>, to: Option<i64>, ) -> usize

Calculate total weight of the vecs for the given range.

pub fn resolve( &self, params: SeriesSelection, max_weight: usize, ) -> Result<ResolvedQuery>

Resolve query metadata without formatting (cheap). Use with format for lazy formatting after ETag check.

pub fn stable_count( &self, index: Index, total: usize, tip_height: Height, ) -> Option<usize>

Count of leading entries provably immutable across a 6-block reorg, used to gate the historical-branch series ETag.

• Bucketed indexes: total - margin.
• Entity indexes: first_X_index[tip_height - 6], falling back to 0 if the tip is shallower than 6 blocks. Clamped to total so a query whose vecs are shorter than the entity-type’s own count never marks its live tail as stable.
• Mutable (Funded/Empty addr): None. No immutable region exists, so the caller must use the tip-bound ETag for every range.

pub fn format(&self, resolved: ResolvedQuery) -> Result<SeriesOutput>

Format a resolved query (expensive). Call after ETag/cache checks to avoid unnecessary work.

pub fn format_raw(&self, resolved: ResolvedQuery) -> Result<SeriesOutput>

Format a resolved query as raw data (just the JSON values, no SeriesData wrapper). Single vec → [v1,v2,...]. Multi-vec → [[v1,v2],[v3,v4],...]. CSV output is identical to format (no wrapper distinction for CSV).

pub fn series_count(&self) -> DetailedSeriesCount

pub fn indexes(&self) -> &'static [IndexInfo]

pub fn series_list(&self, pagination: Pagination) -> PaginatedSeries

pub fn series_catalog(&self) -> &'static TreeNode

pub fn series_info(&self, series: &SeriesName) -> Option<SeriesInfo>

pub fn format_legacy( &self, resolved: ResolvedQuery, ) -> Result<SeriesOutputLegacy>

Deprecated - format a resolved query as legacy output (expensive).

impl Query

pub fn txid_by_index(&self, index: TxIndex) -> Result<Txid>

pub fn resolve_tx(&self, txid: &Txid) -> Result<(TxIndex, Height)>

Resolve a txid to (TxIndex, Height).

pub fn transaction(&self, txid: &Txid) -> Result<Transaction>

pub fn transaction_status(&self, txid: &Txid) -> Result<TxStatus>

pub fn transaction_raw(&self, txid: &Txid) -> Result<Vec<u8>>

pub fn transaction_hex(&self, txid: &Txid) -> Result<String>

pub fn outspend(&self, txid: &Txid, vout: Vout) -> Result<TxOutspend>

pub fn outspends(&self, txid: &Txid) -> Result<Vec<TxOutspend>>

pub fn broadcast_transaction(&self, hex: &str) -> Result<Txid>

pub fn merkleblock_proof(&self, txid: &Txid) -> Result<String>

pub fn merkle_proof(&self, txid: &Txid) -> Result<MerkleProof>

impl Query

pub fn urpd_cohorts(&self) -> Result<Vec<Cohort>>

Available cohorts for URPD.

pub fn urpd_dates(&self, cohort: &Cohort) -> Result<Vec<Date>>

Available dates for a cohort.

pub fn urpd_dates_with_weight( &self, cohort: &Cohort, weight: UrpdWeight, ) -> Result<Vec<Date>>

Available dates for a cohort and weighting.

pub fn urpd_raw(&self, cohort: &Cohort, date: Date) -> Result<UrpdRaw>

Raw URPD data for a cohort on a specific date.

pub fn urpd_raw_with_weight( &self, cohort: &Cohort, date: Date, weight: UrpdWeight, ) -> Result<UrpdRaw>

Raw URPD data with an optional Bedrock weighting.

pub fn urpd_at( &self, cohort: &Cohort, date: Date, agg: UrpdAggregation, ) -> Result<Urpd>

URPD for a cohort on a specific date.

pub fn urpd_at_with_weight( &self, cohort: &Cohort, date: Date, agg: UrpdAggregation, weight: UrpdWeight, ) -> Result<Urpd>

URPD for a cohort on a specific date and weighting.

pub fn urpd_latest(&self, cohort: &Cohort, agg: UrpdAggregation) -> Result<Urpd>

URPD for the most recently available date in a cohort.

pub fn urpd_latest_with_weight( &self, cohort: &Cohort, agg: UrpdAggregation, weight: UrpdWeight, ) -> Result<Urpd>

Most recent URPD for a cohort and weighting.

impl Query

pub fn build( reader: &Reader, indexer: &Indexer, computer: &Computer, mempool: Option<Mempool>, ) -> Self

pub fn height(&self) -> Height

Pipeline-safe ceiling: the highest height for which both the indexer and computer have committed durable data. Backed by Indexer::safe_lengths(), advanced by main.rs after each compute pass and lowered before any rollback.

Returns a height (the last fully-written block), not a length. safe_lengths().height is a count: N means heights 0..N are committed, so the highest is N-1. Pre-genesis (N == 0) falls back to Height::default() and clients treat it as “nothing indexed yet”.

pub fn tip_blockhash(&self) -> BlockHash

Tip block hash at the pipeline-safe ceiling.

pub fn tip_hash_prefix(&self) -> BlockHashPrefix

Tip block hash prefix for cache etags.

pub fn sync_status(&self, tip_height: Height) -> Result<SyncStatus>

Build sync status with the given tip height. indexed_height and computed_height reflect live per-vec stamps (diagnostic) and may be briefly ahead of fully-flushed data; the timestamp data read uses the safe-lengths-derived height so it never outruns committed bytes.

pub fn reader(&self) -> &Reader

pub fn client(&self) -> &Client

pub fn blocks_dir(&self) -> &Path

pub fn indexer(&self) -> &Indexer<Ro>

pub fn computer(&self) -> &Computer<Ro>

pub fn mempool(&self) -> Option<&Mempool>

pub fn vecs(&self) -> &'static Vecs<'static>

Trait Implementations

impl Clone for Query

fn clone(&self) -> Query

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.