Struct zebra_chain::work::difficulty::CompactDifficulty

pub struct CompactDifficulty(pub(crate) u32);

A 32-bit “compact bits” value, which represents the difficulty threshold for a block header.

Used for:

• checking the difficulty_threshold value in the block header,
• calculating the 256-bit ExpandedDifficulty threshold, for comparison with the block header hash, and
• calculating the block work.

Consensus

This is a floating-point encoding, with a 24-bit signed mantissa, an 8-bit exponent, an offset of 3, and a radix of 256. (IEEE 754 32-bit floating-point values use a separate sign bit, an implicit leading mantissa bit, an offset of 127, and a radix of 2.)

The precise bit pattern of a CompactDifficulty value is consensus-critical, because it is used for the difficulty_threshold field, which is:

• part of the BlockHeader, which is used to create the block::Hash, and
• bitwise equal to the median ExpandedDifficulty value of recent blocks, when encoded to CompactDifficulty using the specified conversion function.

Without these consensus rules, some ExpandedDifficulty values would have multiple equivalent CompactDifficulty values, due to redundancy in the floating-point format.

Deterministic conversions between a target threshold and a “compact“ nBits value are not fully defined in the Bitcoin documentation, and so we define them here: (see equations in the Zcash Specification section 7.7.4)

Tuple Fields

0: u32

Implementations

impl CompactDifficulty

const BASE: u32 = 256u32

CompactDifficulty exponent base.

const OFFSET: i32 = 3i32

CompactDifficulty exponent offset.

const PRECISION: u32 = 24u32

CompactDifficulty floating-point precision.

const SIGN_BIT: u32 = 8_388_608u32

CompactDifficulty sign bit, part of the signed mantissa.

const UNSIGNED_MANTISSA_MASK: u32 = 8_388_607u32

CompactDifficulty unsigned mantissa mask.

Also the maximum unsigned mantissa value.

pub fn to_expanded(self) -> Option<ExpandedDifficulty>

Calculate the ExpandedDifficulty for a compact representation.

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

Returns None for negative, zero, and overflow values. (zcashd rejects these values, before comparing the hash.)

pub fn to_work(self) -> Option<Work>

Calculate the Work for a compact representation.

See Definition of Work in the Zcash Specification, and GetBlockProof() in zcashd.

Returns None if the corresponding ExpandedDifficulty is None. Also returns None on Work overflow, which should be impossible on a valid chain.

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

Return the difficulty bytes in big-endian byte-order.

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; 4], ) -> Result<CompactDifficulty, BoxError>

Convert bytes in big-endian byte-order into a CompactDifficulty.

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

Returns an error if the difficulty value is invalid.

pub fn relative_to_network(&self, network: &Network) -> f64

Returns a floating-point number representing a difficulty as a multiple of the minimum difficulty for the provided network.

Trait Implementations

impl Arbitrary for CompactDifficulty

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<CompactDifficulty>

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 CompactDifficulty

fn clone(&self) -> CompactDifficulty

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for CompactDifficulty

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

Formats the value using the given formatter.

impl Default for CompactDifficulty

fn default() -> CompactDifficulty

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for CompactDifficulty

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for CompactDifficulty

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

Formats the value using the given formatter.

impl From<ExpandedDifficulty> for CompactDifficulty

fn from(value: ExpandedDifficulty) -> Self

Converts to this type from the input type.

impl FromHex for CompactDifficulty

type Error = Box<dyn Error + Sync + Send>

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 PartialEq for CompactDifficulty

fn eq(&self, other: &CompactDifficulty) -> 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 Serialize for CompactDifficulty

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl ToHex for &CompactDifficulty

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 CompactDifficulty

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 Copy for CompactDifficulty

impl Eq for CompactDifficulty

impl StructuralPartialEq for CompactDifficulty