Module grin_core::consensus

source ·
Expand description

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§

  • Minimal header information required for the Difficulty calculation to take place. Used to iterate through a number of blocks. Note that an instance of this is unable to calculate its own hash, due to an optimization that prevents the header’s PoW proof nonces from being deserialized on read

Constants§

  • Dampening factor to use for AR scale calculation.
  • Original reference edge_bits to compute difficulty factors for higher Cuckoo graph sizes, changing this would hard fork
  • 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).
  • Average time span of the DMA difficulty adjustment window
  • minimum solution difficulty after HardFork4 when PoW becomes primary only Cuckatoo32+
  • Clamp factor to use for DMA difficulty adjustment Limit value to within this factor of goal
  • Number of blocks before a coinbase matures and can be spent
  • 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.
  • A day is 1440 blocks
  • Default Cuckatoo Cycle edge_bits, used for mining and validating.
  • Dampening factor to use for DMA difficulty adjustment
  • Number of blocks used to calculate difficulty adjustment by Damped Moving Average
  • A grin is divisible to 10^9, following the SI prefixes
  • Fork every 6 months.
  • Nominal height for standard time intervals, hour is 60 blocks
  • an hour in seconds
  • 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)
  • Weight of an input when counted against the max block weight capacity
  • Weight of a kernel when counted against the max block weight capacity
  • Total maximum block weight. At current sizes, this means a maximum theoretical size of:
  • Microgrin, a thousand of a milligrin
  • Milligrin, a thousand of a grin
  • Minimum scaling factor for AR pow, enforced in diff retargetting avoids getting stuck when trying to increase ar_scale subject to dampening
  • Minimum difficulty, enforced in Damped Moving Average diff retargetting avoids getting stuck when trying to increase difficulty subject to dampening
  • Nanogrin, smallest unit, takes a billion to make a grin
  • Weight of an output when counted against the max block weight capacity
  • Cuckoo-cycle proof size (cycle length)
  • The block subsidy amount, one grin per second on average
  • Cuckaroo* proof-of-work edge_bits, meant to be ASIC resistant.
  • 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.
  • Fork every 3 blocks
  • Testnet first hard fork height, set to happen around 2019-06-20
  • Testnet second hard fork height, set to happen around 2020-12-8
  • Testnet second hard fork height, set to happen around 2019-12-19
  • Testnet second hard fork height, set to happen around 2020-06-20
  • unit difficulty, equal to graph_weight(SECOND_POW_EDGE_BITS)
  • A week is 10_080 blocks
  • Difficulty adjustment half life (actually, 60s * number of 0s-blocks to raise diff by factor e) is 4 hours
  • A year is 524_160 blocks

Functions§

  • Count, in units of 1/100 (a percent), the number of “secondary” (AR) blocks in the provided window of blocks.
  • limit value to be within some factor from a goal
  • Move value linearly toward a goal
  • 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
  • Compute possible block version at a given height, implements 6 months interval scheduled hard forks for the first 2 years.
  • 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
  • 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.
  • 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.
  • Actual block reward for a given total fee amount
  • 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.
  • 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
  • Check whether the block version is valid at a given height, implements 6 months interval scheduled hard forks for the first 2 years.