Module grin_core::consensus

All the rules required for a cryptocurrency to have reach consensus across the whole network are complex and hard to completely isolate. Some can be simple parameters (like block reward), others complex algorithms (like Merkle sum trees or reorg rules). However, as long as they're simple enough, consensus-relevant constants and short functions should be kept here.

Structs

HeaderInfo

Minimal header information required for the Difficulty calculation to take place

Constants

AR_SCALE_DAMP_FACTOR	Dampening factor to use for AR scale calculation.
BASE_EDGE_BITS	Original reference edge_bits to compute difficulty factors for higher Cuckoo graph sizes, changing this would hard fork
BLOCK_INPUT_WEIGHT	Weight of an input when counted against the max block weight capacity
BLOCK_KERNEL_WEIGHT	Weight of a kernel when counted against the max block weight capacity
BLOCK_OUTPUT_WEIGHT	Weight of an output when counted against the max block weight capacity
BLOCK_TIME_SEC	Block interval, in seconds, the network will tune its next_target for. Note that we may reduce this value in the future as we get more data on mining with Cuckoo Cycle, networks improve and block propagation is optimized (adjusting the reward accordingly).
BLOCK_TIME_WINDOW	Average time span of the difficulty adjustment window
CLAMP_FACTOR	Clamp factor to use for difficulty adjustment Limit value to within this factor of goal
COINBASE_MATURITY	Number of blocks before a coinbase matures and can be spent
CUT_THROUGH_HORIZON	Default number of blocks in the past when cross-block cut-through will start happening. Needs to be long enough to not overlap with a long reorg. Rational behind the value is the longest bitcoin fork was about 30 blocks, so 5h. We add an order of magnitude to be safe and round to 7x24h of blocks to make it easier to reason about.
DAY_HEIGHT	A day is 1440 blocks
DEFAULT_MIN_EDGE_BITS	Default Cuckatoo Cycle edge_bits, used for mining and validating.
DIFFICULTY_ADJUST_WINDOW	Number of blocks used to calculate difficulty adjustments
DIFFICULTY_DAMP_FACTOR	Dampening factor to use for difficulty adjustment
GRIN_BASE	A grin is divisible to 10^9, following the SI prefixes
HARD_FORK_INTERVAL	Fork every 6 months.
HOUR_HEIGHT	Nominal height for standard time intervals, hour is 60 blocks
INITIAL_DIFFICULTY	The initial difficulty at launch. This should be over-estimated and difficulty should come down at launch rather than up Currently grossly over-estimated at 10% of current ethereum GPUs (assuming 1GPU can solve a block at diff 1 in one block interval)
MAX_BLOCK_WEIGHT	Total maximum block weight. At current sizes, this means a maximum theoretical size of:
MICRO_GRIN	Microgrin, a thousand of a milligrin
MILLI_GRIN	Milligrin, a thousand of a grin
MIN_AR_SCALE	Minimum scaling factor for AR pow, enforced in diff retargetting avoids getting stuck when trying to increase ar_scale subject to dampening
MIN_DIFFICULTY	Minimum difficulty, enforced in diff retargetting avoids getting stuck when trying to increase difficulty subject to dampening
NANO_GRIN	Nanogrin, smallest unit, takes a billion to make a grin
PROOFSIZE	Cuckoo-cycle proof size (cycle length)
REWARD	The block subsidy amount, one grin per second on average
SECOND_POW_EDGE_BITS	Cuckaroo proof-of-work edge_bits, meant to be ASIC resistant.
STATE_SYNC_THRESHOLD	Default number of blocks in the past to determine the height where we request a txhashset (and full blocks from). Needs to be long enough to not overlap with a long reorg. Rational behind the value is the longest bitcoin fork was about 30 blocks, so 5h. We add an order of magnitude to be safe and round to 2x24h of blocks to make it easier to reason about.
UNIT_DIFFICULTY	unit difficulty, equal to graph_weight(SECOND_POW_EDGE_BITS)
WEEK_HEIGHT	A week is 10_080 blocks
YEAR_HEIGHT	A year is 524_160 blocks

Functions

ar_count	Count, in units of 1/100 (a percent), the number of "secondary" (AR) blocks in the provided window of blocks.
clamp	limit value to be within some factor from a goal
damp	Move value linearly toward a goal
graph_weight	Compute weight of a graph as number of siphash bits defining the graph Must be made dependent on height to phase out smaller size over the years This can wait until end of 2019 at latest
next_difficulty	Computes the proof-of-work difficulty that the next block should comply with. Takes an iterator over past block headers information, from latest (highest height) to oldest (lowest height).
reward	Actual block reward for a given total fee amount
secondary_pow_ratio	Ratio the secondary proof of work should take over the primary, as a function of block height (time). Starts at 90% losing a percent approximately every week. Represented as an integer between 0 and 100.
secondary_pow_scaling	Factor by which the secondary proof of work difficulty will be adjusted
valid_header_version	Check whether the block version is valid at a given height, implements 6 months interval scheduled hard forks for the first 2 years.