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_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 DMA difficulty adjustment window
C32_GRAPH_WEIGHT	minimum solution difficulty after HardFork4 when PoW becomes primary only Cuckatoo32+
CLAMP_FACTOR	Clamp factor to use for DMA 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.
DMA_DAMP_FACTOR	Dampening factor to use for DMA difficulty adjustment
DMA_WINDOW	Number of blocks used to calculate difficulty adjustment by Damped Moving Average
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
HOUR_SEC	an hour in seconds
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)
INPUT_WEIGHT	Weight of an input when counted against the max block weight capacity
KERNEL_WEIGHT	Weight of a kernel when counted against the max block weight capacity
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_DMA_DIFFICULTY	Minimum difficulty, enforced in Damped Moving Average 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
OUTPUT_WEIGHT	Weight of an output when counted against the max block weight capacity
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.
TESTING_HARD_FORK_INTERVAL	Fork every 3 blocks
TESTNET_FIRST_HARD_FORK	Testnet first hard fork height, set to happen around 2019-06-20
TESTNET_FOURTH_HARD_FORK	Testnet second hard fork height, set to happen around 2020-12-8
TESTNET_SECOND_HARD_FORK	Testnet second hard fork height, set to happen around 2019-12-19
TESTNET_THIRD_HARD_FORK	Testnet second hard fork height, set to happen around 2020-06-20
UNIT_DIFFICULTY	unit difficulty, equal to graph_weight(SECOND_POW_EDGE_BITS)
WEEK_HEIGHT	A week is 10_080 blocks
WTEMA_HALF_LIFE	Difficulty adjustment half life (actually, 60s * number of 0s-blocks to raise diff by factor e) is 4 hours
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 The height dependence allows a 30-week linear transition from C31+ to C32+ starting after 1 year
header_version	Compute possible block version at a given height, implements 6 months interval scheduled hard forks for the first 2 years.
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). Uses either the old dma DAA or, starting from HF4, the new wtema DAA
next_dma_difficulty	Difficulty calculation based on a Damped Moving Average of difficulty over a window of DMA_WINDOW blocks. The corresponding timespan is calculated by using the difference between the timestamps at the beginning and the end of the window, with a damping toward the target block time.
next_wtema_difficulty	Difficulty calculation based on a Weighted Target Exponential Moving Average of difficulty, using the ratio of the last block time over the target block time.
reward	Actual block reward for a given total fee amount
secondary_pow_ratio	Target ratio of secondary proof of work to primary proof of work, 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	The secondary proof-of-work factor is calculated along the same lines as in next_dma_difficulty, as an adjustment on the deviation against the ideal value. 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.