Struct AdjustedDifficulty

pub(crate) struct AdjustedDifficulty {
    candidate_time: DateTime<Utc>,
    candidate_height: Height,
    network: Network,
    relevant_difficulty_thresholds: Vec<CompactDifficulty>,
    relevant_times: Vec<DateTime<Utc>>,
}

Contains the context needed to calculate the adjusted difficulty for a block.

Fields

candidate_time: DateTime<Utc>

The header.time field from the candidate block

candidate_height: Height

The coinbase height from the candidate block

If we only have the header, this field is calculated from the previous block height.

network: Network

The configured network

relevant_difficulty_thresholds: Vec<CompactDifficulty>

The header.difficulty_thresholds from the previous PoWAveragingWindow + PoWMedianBlockSpan (28) blocks, in reverse height order.

relevant_times: Vec<DateTime<Utc>>

The header.times from the previous PoWAveragingWindow + PoWMedianBlockSpan (28) blocks, in reverse height order.

Only the first and last PoWMedianBlockSpan times are used. Times 11..=16 are ignored.

Implementations

impl AdjustedDifficulty

pub fn new_from_block<C>( candidate_block: &Block, network: &Network, context: C, ) -> AdjustedDifficulty

where C: IntoIterator<Item = (CompactDifficulty, DateTime<Utc>)>,

Initialise and return a new AdjustedDifficulty using a candidate_block, network, and a context.

The context contains the previous PoWAveragingWindow + PoWMedianBlockSpan (28) difficulty_thresholds and times from the relevant chain for candidate_block, in reverse height order, starting with the previous block.

Note that the times might not be in reverse chronological order, because block times are supplied by miners.

Panics

If the context contains fewer than 28 items.

pub fn new_from_header_time<C>( candidate_header_time: DateTime<Utc>, previous_block_height: Height, network: &Network, context: C, ) -> AdjustedDifficulty

where C: IntoIterator<Item = (CompactDifficulty, DateTime<Utc>)>,

Initialise and return a new AdjustedDifficulty using a candidate_header_time, previous_block_height, network, and a context.

Designed for use when validating block headers, where the full block has not been downloaded yet.

See Self::new_from_block for detailed information about the context.

Panics

If the context contains fewer than 28 items.

pub fn candidate_height(&self) -> Height

Returns the candidate block’s height.

pub fn candidate_time(&self) -> DateTime<Utc>

Returns the candidate block’s time field.

pub fn network(&self) -> Network

Returns the configured network.

pub fn expected_difficulty_threshold(&self) -> CompactDifficulty

Calculate the expected difficulty_threshold for a candidate block, based on the candidate_time, candidate_height, network, and the difficulty_thresholds and times from the previous PoWAveragingWindow + PoWMedianBlockSpan (28) blocks in the relevant chain.

Implements ThresholdBits from the Zcash specification, and the Testnet minimum difficulty adjustment from ZIPs 205 and 208.

fn threshold_bits(&self) -> CompactDifficulty

Calculate the difficulty_threshold for a candidate block, based on the candidate_height, network, and the relevant difficulty_thresholds and times.

See Self::expected_difficulty_threshold for details.

Implements ThresholdBits from the Zcash specification. (Which excludes the Testnet minimum difficulty adjustment.)

fn mean_target_difficulty(&self) -> ExpandedDifficulty

Calculate the arithmetic mean of the averaging window thresholds: the expanded difficulty_thresholds from the previous PoWAveragingWindow (17) blocks in the relevant chain.

Implements MeanTarget from the Zcash specification.

fn median_timespan_bounded(&self) -> Duration

Calculate the bounded median timespan. The median timespan is the difference of medians of the timespan times, which are the times from the previous PoWAveragingWindow + PoWMedianBlockSpan (28) blocks in the relevant chain.

Uses the candidate block’s height' and networkto calculate theAveragingWindowTimespan` for that block.

The median timespan is damped by the PoWDampingFactor, and bounded by PoWMaxAdjustDown and PoWMaxAdjustUp.

Implements ActualTimespanBounded from the Zcash specification.

Note: This calculation only uses PoWMedianBlockSpan (11) times at the start and end of the timespan times. timespan times [11..=16] are ignored.

fn median_timespan(&self) -> Duration

Calculate the median timespan. The median timespan is the difference of medians of the timespan times, which are the times from the previous PoWAveragingWindow + PoWMedianBlockSpan (28) blocks in the relevant chain.

Implements ActualTimespan from the Zcash specification.

See Self::median_timespan_bounded for details.

pub fn median_time_past(&self) -> DateTime<Utc>

Calculate the median of the times from the previous PoWMedianBlockSpan (11) blocks in the relevant chain.

Implements median-time-past and MedianTime(candidate_height) from the Zcash specification. (These functions are identical, but they are specified in slightly different ways.)

pub(crate) fn median_time( median_block_span_times: Vec<DateTime<Utc>>, ) -> DateTime<Utc>

Calculate the median of the median_block_span_times: the times from a Vec of PoWMedianBlockSpan (11) or fewer blocks in the relevant chain.

Implements MedianTime from the Zcash specification.

Panics

If provided an empty Vec