Struct zebra_chain::work::difficulty::ExpandedDifficulty

pub struct ExpandedDifficulty(U256);

A 256-bit unsigned “expanded difficulty” value.

Used as a target threshold for the difficulty of a block::Hash.

Consensus

The precise bit pattern of an ExpandedDifficulty value is consensus-critical, because it is compared with the block::Hash.

Note that each CompactDifficulty value can be converted from a range of ExpandedDifficulty values, because the precision of the floating-point format requires rounding on conversion.

Therefore, consensus-critical code must perform the specified conversions to CompactDifficulty, even if the original ExpandedDifficulty values are known.

Callers should avoid constructing ExpandedDifficulty zero values, because they are rejected by the consensus rules, and cause some conversion functions to panic.

The difficulty filter is unchanged from Bitcoin, and is calculated using SHA-256d on the whole block header (including solutionSize and solution). The result is interpreted as a 256-bit integer represented in little-endian byte order, which MUST be less than or equal to the target threshold given by ToTarget(nBits).

Zcash Specification section 7.7.2.

Tuple Fields

0: U256

Implementations

impl ExpandedDifficulty

pub(super) fn from_hash(hash: &Hash) -> ExpandedDifficulty

Returns the difficulty of the hash.

Used to implement comparisons between difficulties and hashes.

Usage:

Compare the hash with the calculated difficulty value, using Rust’s standard comparison operators.

Hashes are not used to calculate the difficulties of future blocks, so users of this module should avoid converting hashes into difficulties.

pub fn to_compact(self) -> CompactDifficulty

Calculate the CompactDifficulty for an expanded difficulty.

Consensus

See ToCompact() in the Zcash Specification, and GetCompact() in zcashd: https://zips.z.cash/protocol/protocol.pdf#nbits

Panics

If self is zero.

ExpandedDifficulty values are generated in two ways:

• conversion from CompactDifficulty values, which rejects zeroes, and
• difficulty adjustment calculations, which impose a non-zero minimum target_difficulty_limit.

Neither of these methods yield zero values.

pub fn bytes_in_display_order(&self) -> [u8; 32]

Return the difficulty bytes in big-endian byte-order, suitable for printing out byte by byte.

Zebra displays difficulties in big-endian byte-order, following the u256 convention set by Bitcoin and zcashd.

pub fn from_bytes_in_display_order( bytes_in_display_order: &[u8; 32], ) -> ExpandedDifficulty

Convert bytes in big-endian byte-order into an ExpandedDifficulty.

Zebra displays difficulties in big-endian byte-order, following the u256 convention set by Bitcoin and zcashd.

Preserves the exact difficulty value represented by the bytes, even if it can’t be generated from a CompactDifficulty. This means a round-trip conversion to CompactDifficulty can be lossy.

Trait Implementations

impl Arbitrary for ExpandedDifficulty

type Parameters = ()

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

fn arbitrary_with(_args: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args.

type Strategy = BoxedStrategy<ExpandedDifficulty>

The type of Strategy used to generate values of type Self.

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self).

impl Clone for ExpandedDifficulty

fn clone(&self) -> ExpandedDifficulty

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ExpandedDifficulty

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for ExpandedDifficulty

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Div<T> for ExpandedDifficulty

where T: Into<U256>,

type Output = ExpandedDifficulty

The resulting type after applying the / operator.

fn div(self, rhs: T) -> Self::Output

Performs the / operation.

impl From<ExpandedDifficulty> for CompactDifficulty

fn from(value: ExpandedDifficulty) -> Self

Converts to this type from the input type.

impl From<ExpandedDifficulty> for U256

fn from(value: ExpandedDifficulty) -> Self

Converts to this type from the input type.

impl From<U256> for ExpandedDifficulty

fn from(value: U256) -> Self

Converts to this type from the input type.

impl FromHex for ExpandedDifficulty

type Error = <[u8; 32] as FromHex>::Error

fn from_hex<T: AsRef<[u8]>>(hex: T) -> Result<Self, Self::Error>

Creates an instance of type Self from the given hex string, or fails with a custom error type.

impl Hash for ExpandedDifficulty

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> Mul<T> for ExpandedDifficulty

where U256: Mul<T>, <U256 as Mul<T>>::Output: Into<U256>,

type Output = ExpandedDifficulty

The resulting type after applying the * operator.

fn mul(self, rhs: T) -> ExpandedDifficulty

Performs the * operation.

impl Ord for ExpandedDifficulty

fn cmp(&self, other: &ExpandedDifficulty) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq<ExpandedDifficulty> for Hash

fn eq(&self, other: &ExpandedDifficulty) -> bool

Is self equal to other?

See <ExpandedDifficulty as PartialOrd<block::Hash>::partial_cmp for details.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Hash> for ExpandedDifficulty

fn eq(&self, other: &Hash) -> bool

Is self equal to other?

See partial_cmp for details.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for ExpandedDifficulty

fn eq(&self, other: &ExpandedDifficulty) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<ExpandedDifficulty> for Hash

fn partial_cmp(&self, other: &ExpandedDifficulty) -> Option<Ordering>

How does self compare to other?

Consensus

See <ExpandedDifficulty as PartialOrd<block::Hash>::partial_cmp for details.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Hash> for ExpandedDifficulty

fn partial_cmp(&self, other: &Hash) -> Option<Ordering>

Consensus

block::Hashes are compared with ExpandedDifficulty thresholds by converting the hash to a 256-bit integer in little-endian order.

Greater values represent less work. This matches the convention in zcashd and bitcoin.

https://zips.z.cash/protocol/protocol.pdf#workdef

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd for ExpandedDifficulty

fn partial_cmp(&self, other: &ExpandedDifficulty) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Sum for ExpandedDifficulty

fn sum<I: Iterator<Item = ExpandedDifficulty>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by “summing up” the items.

impl ToHex for &ExpandedDifficulty

fn encode_hex<T: FromIterator<char>>(&self) -> T

Encode the hex strict representing self into the result. Lower case letters are used (e.g. f9b4ca)

fn encode_hex_upper<T: FromIterator<char>>(&self) -> T

Encode the hex strict representing self into the result. Upper case letters are used (e.g. F9B4CA)

impl ToHex for ExpandedDifficulty

fn encode_hex<T: FromIterator<char>>(&self) -> T

Encode the hex strict representing self into the result. Lower case letters are used (e.g. f9b4ca)

fn encode_hex_upper<T: FromIterator<char>>(&self) -> T

Encode the hex strict representing self into the result. Upper case letters are used (e.g. F9B4CA)

impl TryFrom<ExpandedDifficulty> for Work

type Error = ()

The type returned in the event of a conversion error.

fn try_from(expanded: ExpandedDifficulty) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for ExpandedDifficulty

impl Eq for ExpandedDifficulty

impl StructuralPartialEq for ExpandedDifficulty