# README
primitives
Package and Module Status
This package is currently a work in progress in the context of a larger refactor and thus does not yet provide most of the things that are ultimately planned. See https://github.com/decred/dcrd/issues/2786 for further details.
The intention is to create a containing primitives module that will be kept at
an experimental module version ("v0") until everything is stabilized to avoid
major module version churn in the mean time.
Overview
This package ultimately aims to provide core data structures and functions for working with several aspects of Decred consensus.
The provided functions fall into the following categories:
- Proof-of-work
- Converting to and from the target difficulty bits representation
- Calculating work values based on the target difficulty bits
- Checking that a block hash satisfies a target difficulty and that the target difficulty is within a valid range
- Merkle root calculation
- Calculation from individual leaf hashes
- Inclusion proofs
- Generating Merkle tree inclusion proofs
- Verifying Merkle tree inclusion proofs
- Subsidy calculation
- Proof-of-work subsidy for a given height and number of votes
- Stake vote subsidy for a given height
- Treasury subsidy for a given height and number of votes
Maintainer Note
Since the primitives module is heavily relied upon by consensus code, there
are some important aspects that must be kept in mind when working on this code:
- It must provide correctness guarantees and full test coverage
- Be extremely careful when making any changes to avoid breaking consensus
- This often means existing code can't be changed without adding an internal flag to control behavior and introducing a new method with the new behavior
- Minimize the number of allocations as much as possible
- Opt for data structures that improve cache locality
- Keep a strong focus on providing efficient code
- Avoid external dependencies
- Consensus code requires much stronger guarantees than typical code and consequently code that is not specifically designed with such rigid constraints will almost always eventually break things in subtle ways over time
- Do not change the API in a way that requires a new major semantic version
- This is not entirely prohibited, but major module version bumps have severe ramifications on every consumer, and thus they should be an absolute last resort
- Take care when adding new methods to avoid method signatures that would require a major version bump due to a new major dependency version
Installation and Updating
This package is internal and therefore is neither directly installed nor needs to be manually updated.
License
Package primitives is licensed under the copyfree ISC License.
# Functions
CalcMerkleRoot treats the provided slice of hashes as leaves of a merkle tree and returns the resulting merkle root.
CalcMerkleRootInPlace is an in-place version of CalcMerkleRoot that reuses the backing array of the provided slice to perform the calculation thereby preventing extra allocations.
CalcWork calculates a work value from difficulty bits.
CheckProofOfWork ensures the provided hash is less than the target difficulty represented by given header bits and that said difficulty is in min/max range per the provided proof-of-work limit.
CheckProofOfWorkRange ensures the provided target difficulty represented by the given header bits is in min/max range per the provided proof-of-work limit.
DiffBitsToUint256 converts the compact representation used to encode difficulty targets to an unsigned 256-bit integer.
GenerateInclusionProof treats the provided slice of hashes as leaves of a merkle tree and generates and returns a merkle tree inclusion proof for the given leaf index.
HashToUint256 converts the provided hash to an unsigned 256-bit integer that can be used to perform math comparisons.
NewSubsidyCache creates and initializes a new subsidy cache instance.
Uint256ToDiffBits converts a uint256 to a compact representation using an unsigned 32-bit integer.
VerifyInclusionProof returns whether or not the given leaf hash, original leaf index, and inclusion proof result in recalculating a merkle root that matches the provided merkle root.
# Constants
ErrHighHash indicates the block does not hash to a value which is lower than the required target difficultly.
ErrUnexpectedDifficulty indicates specified bits do not align with the expected value either because it doesn't match the calculated value based on difficulty rules or it is out of the valid range.
# Structs
RuleError identifies a rule violation.
SubsidyCache provides efficient access to consensus-critical subsidy calculations for blocks and votes, including the max potential subsidy for given block heights, the proportional proof-of-work subsidy, the proportional proof of stake per-vote subsidy, and the proportional treasury subsidy.
# Interfaces
SubsidyParams defines an interface that is used to provide the parameters required when calculating block and vote subsidies.
# Type aliases
ErrorKind identifies a kind of error.