nimbus-eth2/beacon_chain/fork_choice/proto_array.nim

554 lines
20 KiB
Nim
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# beacon_chain
# Copyright (c) 2018-2022 Status Research & Development GmbH
# Licensed and distributed under either of
# * MIT license (license terms in the root directory or at https://opensource.org/licenses/MIT).
# * Apache v2 license (license terms in the root directory or at https://www.apache.org/licenses/LICENSE-2.0).
# at your option. This file may not be copied, modified, or distributed except according to those terms.
{.push raises: [Defect].}
import
# Standard library
std/[options, tables, typetraits],
# Status libraries
chronicles,
stew/results,
# Internal
../spec/datatypes/base,
# Fork choice
./fork_choice_types
logScope:
topics = "fork_choice"
export results
# https://github.com/ethereum/consensus-specs/blob/v0.11.1/specs/phase0/fork-choice.md
# This is a port of https://github.com/sigp/lighthouse/pull/804
# which is a port of "Proto-Array": https://github.com/protolambda/lmd-ghost
# See also:
# - Protolambda port of Lighthouse: https://github.com/protolambda/eth2-py-hacks/blob/ae286567/proto_array.py
# - Prysmatic writeup: https://hackmd.io/bABJiht3Q9SyV3Ga4FT9lQ#High-level-concept
# - Gasper Whitepaper: https://arxiv.org/abs/2003.03052
# Helpers
# ----------------------------------------------------------------------
func tiebreak(a, b: Eth2Digest): bool =
## Fork-Choice tie-break between 2 digests
## Currently implemented as `>=` (greater or equal)
## on the binary representation
for i in 0 ..< a.data.len:
if a.data[i] < b.data[i]:
return false
elif a.data[i] > b.data[i]:
return true
# else we have equality so far
return true
template unsafeGet*[K, V](table: Table[K, V], key: K): V =
## Get a value from a Nim Table, turning KeyError into
## an AssertionError defect
# Pointer is used to work around the lack of a `var` withValue
try:
table[key]
except KeyError as exc:
raiseAssert(exc.msg)
func `[]`(nodes: ProtoNodes, idx: Index): Option[ProtoNode] =
## Retrieve a ProtoNode at "Index"
if idx < nodes.offset:
return none(ProtoNode)
let i = idx - nodes.offset
if i >= nodes.buf.len:
return none(ProtoNode)
some(nodes.buf[i])
func len*(nodes: ProtoNodes): int =
nodes.buf.len
func add(nodes: var ProtoNodes, node: ProtoNode) =
nodes.buf.add node
# Forward declarations
# ----------------------------------------------------------------------
func maybeUpdateBestChildAndDescendant(self: var ProtoArray,
parentIdx: Index,
childIdx: Index): FcResult[void]
func nodeIsViableForHead(self: ProtoArray, node: ProtoNode): bool
func nodeLeadsToViableHead(self: ProtoArray, node: ProtoNode): FcResult[bool]
# ProtoArray routines
# ----------------------------------------------------------------------
func init*(T: type ProtoArray,
justifiedCheckpoint: Checkpoint,
finalizedCheckpoint: Checkpoint): T =
let node = ProtoNode(
root: finalizedCheckpoint.root,
parent: none(int),
justifiedCheckpoint: justifiedCheckpoint,
finalizedCheckpoint: finalizedCheckpoint,
weight: 0,
bestChild: none(int),
bestDescendant: none(int)
)
T(
justifiedCheckpoint: justifiedCheckpoint,
finalizedCheckpoint: finalizedCheckpoint,
nodes: ProtoNodes(buf: @[node], offset: 0),
indices: {node.root: 0}.toTable()
)
# https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md#configuration
# https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md#get_latest_attesting_balance
func calculateProposerBoost(validatorBalances: openArray[Gwei]): int64 =
const PROPOSER_SCORE_BOOST = 70
var
total_balance: uint64
num_validators: int64
for balance in validatorBalances:
# We need to filter zero balances here to get an accurate active validator
# count. This is because we default inactive validator balances to zero
# when creating this balances array.
if balance != 0:
total_balance += balance
num_validators += 1
if num_validators == 0:
return 0
let
average_balance = int64(total_balance div num_validators.uint64)
committee_size = num_validators div SLOTS_PER_EPOCH.int64
committee_weight = committee_size * average_balance
(committee_weight * PROPOSER_SCORE_BOOST) div 100
func applyScoreChanges*(self: var ProtoArray,
deltas: var openArray[Delta],
justifiedCheckpoint: Checkpoint,
finalizedCheckpoint: Checkpoint,
newBalances: openArray[Gwei],
proposerBoostRoot: Eth2Digest,
useProposerBoost: bool): FcResult[void] =
## Iterate backwards through the array, touching all nodes and their parents
## and potentially the best-child of each parent.
#
# The structure of `self.nodes` array ensures that the child of each node
# is always touched before its parent.
#
# For each node the following is done:
#
# 1. Update the node's weight with the corresponding delta.
# 2. Backpropagate each node's delta to its parent's delta.
# 3. Compare the current node with the parent's best-child,
# updating if the current node should become the best-child
# 4. If required, update the parent's best-descendant with the current node
# or its best-descendant
#
# useProposerBoost is temporary, until it can be either permanently enabled
# or is removed from the Eth2 spec.
doAssert self.indices.len == self.nodes.len # By construction
if deltas.len != self.indices.len:
return err ForkChoiceError(
kind: fcInvalidDeltaLen,
deltasLen: deltas.len,
indicesLen: self.indices.len)
self.justifiedCheckpoint = justifiedCheckpoint
self.finalizedCheckpoint = finalizedCheckpoint
## Alias
# This cannot raise the IndexError exception, how to tell compiler?
template node: untyped {.dirty.} =
self.nodes.buf[nodePhysicalIdx]
# Default value, if not otherwise set in first node loop
var proposerBoostScore: int64
# Iterate backwards through all the indices in `self.nodes`
for nodePhysicalIdx in countdown(self.nodes.len - 1, 0):
if node.root.isZero:
continue
var nodeDelta = deltas[nodePhysicalIdx]
# If we find the node for which the proposer boost was previously applied,
# decrease the delta by the previous score amount.
if useProposerBoost and
(not self.previousProposerBoostRoot.isZero) and
self.previousProposerBoostRoot == node.root:
if nodeDelta < 0 and
nodeDelta - low(Delta) < self.previousProposerBoostScore:
return err ForkChoiceError(
kind: fcDeltaUnderflow,
index: nodePhysicalIdx)
nodeDelta -= self.previousProposerBoostScore
# If we find the node matching the current proposer boost root, increase
# the delta by the new score amount.
#
# https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md#get_latest_attesting_balance
if useProposerBoost and (not proposer_boost_root.isZero) and
proposer_boost_root == node.root:
proposerBoostScore = calculateProposerBoost(newBalances)
if nodeDelta >= 0 and
high(Delta) - nodeDelta < self.previousProposerBoostScore:
return err ForkChoiceError(
kind: fcDeltaOverflow,
index: nodePhysicalIdx)
nodeDelta += proposerBoostScore.int64
# Apply the delta to the node
# We fail fast if underflow, which shouldn't happen.
# Note that delta can be negative but weight cannot
let weight = node.weight + nodeDelta
if weight < 0:
return err ForkChoiceError(
kind: fcDeltaUnderflow,
index: nodePhysicalIdx)
node.weight = weight
# If the node has a parent, try to update its best-child and best-descendent
if node.parent.isSome():
let parentLogicalIdx = node.parent.unsafeGet()
let parentPhysicalIdx = parentLogicalIdx - self.nodes.offset
if parentPhysicalIdx < 0:
# Orphan, for example
# 0
# / \
# 2 1
# |
# 3
# |
# 4
# -------pruned here ------
# 5 6
# |
# 7
# |
# 8
# / \
# 9 10
#
# with 5 the canonical chain and 6 a discarded fork
# that will be pruned next.
continue
if parentPhysicalIdx >= deltas.len:
return err ForkChoiceError(
kind: fcInvalidParentDelta,
index: parentPhysicalIdx)
# Back-propagate the nodes delta to its parent.
deltas[parentPhysicalIdx] += nodeDelta
# After applying all deltas, update the `previous_proposer_boost`.
if useProposerBoost:
self.previousProposerBoostRoot = proposerBoostRoot
self.previousProposerBoostScore = proposerBoostScore
for nodePhysicalIdx in countdown(self.nodes.len - 1, 0):
if node.root.isZero:
continue
if node.parent.isSome():
let parentLogicalIdx = node.parent.unsafeGet()
let parentPhysicalIdx = parentLogicalIdx - self.nodes.offset
if parentPhysicalIdx < 0:
# Orphan
continue
let nodeLogicalIdx = nodePhysicalIdx + self.nodes.offset
? self.maybeUpdateBestChildAndDescendant(parentLogicalIdx, nodeLogicalIdx)
ok()
func onBlock*(self: var ProtoArray,
root: Eth2Digest,
parent: Eth2Digest,
justifiedCheckpoint: Checkpoint,
finalizedCheckpoint: Checkpoint): FcResult[void] =
## Register a block with the fork choice
## A block `hasParentInForkChoice` may be false
## on fork choice initialization:
## - either from Genesis
## - or from a finalized state loaded from database
# Note: if parent is an "Option" type, we can run out of stack space.
# If the block is already known, ignore it
if root in self.indices:
return ok()
var parentIdx: Index
self.indices.withValue(parent, index) do:
parentIdx = index[]
do:
return err ForkChoiceError(
kind: fcUnknownParent,
childRoot: root,
parentRoot: parent)
let nodeLogicalIdx = self.nodes.offset + self.nodes.buf.len
let node = ProtoNode(
root: root,
parent: some(parentIdx),
justifiedCheckpoint: justifiedCheckpoint,
finalizedCheckpoint: finalizedCheckpoint,
weight: 0,
bestChild: none(int),
bestDescendant: none(int)
)
self.indices[node.root] = nodeLogicalIdx
self.nodes.add node
? self.maybeUpdateBestChildAndDescendant(parentIdx, nodeLogicalIdx)
ok()
func findHead*(self: var ProtoArray,
head: var Eth2Digest,
justifiedRoot: Eth2Digest): FcResult[void] =
## Follows the best-descendant links to find the best-block (i.e. head-block)
##
## Warning
## The result may not be accurate if `onBlock` is not followed by
## `applyScoreChanges` as `onBlock` does not update the whole tree.
var justifiedIdx: Index
self.indices.withValue(justifiedRoot, value) do:
justifiedIdx = value[]
do:
return err ForkChoiceError(
kind: fcJustifiedNodeUnknown,
blockRoot: justifiedRoot)
let justifiedNode = self.nodes[justifiedIdx]
if justifiedNode.isNone():
return err ForkChoiceError(
kind: fcInvalidJustifiedIndex,
index: justifiedIdx)
let bestDescendantIdx = justifiedNode.get().bestDescendant.get(justifiedIdx)
let bestNode = self.nodes[bestDescendantIdx]
if bestNode.isNone():
return err ForkChoiceError(
kind: fcInvalidBestDescendant,
index: bestDescendantIdx)
# Perform a sanity check to ensure the node can be head
if not self.nodeIsViableForHead(bestNode.get()):
return err ForkChoiceError(
kind: fcInvalidBestNode,
startRoot: justifiedRoot,
fkChoiceJustifiedCheckpoint: self.justifiedCheckpoint,
fkChoiceFinalizedCheckpoint: self.finalizedCheckpoint,
headRoot: justifiedNode.get().root,
headJustifiedCheckpoint: justifiedNode.get().justifiedCheckpoint,
headFinalizedCheckpoint: justifiedNode.get().finalizedCheckpoint)
head = bestNode.get().root
ok()
func prune*(self: var ProtoArray, finalizedRoot: Eth2Digest): FcResult[void] =
## Update the tree with new finalization information.
## The tree is pruned if and only if:
## - The `finalizedRoot` and finalized epoch are different from current
##
## Returns error if:
## - The finalized epoch is less than the current one
## - The finalized epoch matches the current one but the finalized root is different
## - Internal error due to invalid indices in `self`
var finalizedIdx: int
self.indices.withValue(finalizedRoot, value) do:
finalizedIdx = value[]
do:
return err ForkChoiceError(
kind: fcFinalizedNodeUnknown,
blockRoot: finalizedRoot)
if finalizedIdx == self.nodes.offset:
# Nothing to do
return ok()
if finalizedIdx < self.nodes.offset:
return err ForkChoiceError(
kind: fcPruningFromOutdatedFinalizedRoot,
finalizedRoot: finalizedRoot)
trace "Pruning blocks from fork choice",
finalizedRoot = shortlog(finalizedRoot)
let finalPhysicalIdx = finalizedIdx - self.nodes.offset
for nodeIdx in 0 ..< finalPhysicalIdx:
self.indices.del(self.nodes.buf[nodeIdx].root)
# Drop all nodes prior to finalization.
# This is done in-place with `moveMem` to avoid costly reallocations.
static: doAssert ProtoNode.supportsCopyMem(), "ProtoNode must be a trivial type"
let tail = self.nodes.len - finalPhysicalIdx
# TODO: can we have an unallocated `self.nodes`? i.e. self.nodes[0] is nil
moveMem(self.nodes.buf[0].addr, self.nodes.buf[finalPhysicalIdx].addr, tail * sizeof(ProtoNode))
self.nodes.buf.setLen(tail)
# update offset
self.nodes.offset = finalizedIdx
ok()
func maybeUpdateBestChildAndDescendant(self: var ProtoArray,
parentIdx: Index,
childIdx: Index): FcResult[void] =
## Observe the parent at `parentIdx` with respect to the child at `childIdx` and
## potentially modify the `parent.bestChild` and `parent.bestDescendant` values
##
## There are four scenarios:
##
## 1. The child is already the best child
## but it's now invalid due to a FFG change and should be removed.
## 2. The child is already the best child
## and the parent is updated with the new best descendant
## 3. The child is not the best child but becomes the best child
## 4. The child is not the best child and does not become the best child
let child = self.nodes[childIdx]
if child.isNone():
return err ForkChoiceError(
kind: fcInvalidNodeIndex,
index: childIdx)
let parent = self.nodes[parentIdx]
if parent.isNone():
return err ForkChoiceError(
kind: fcInvalidNodeIndex,
index: parentIdx)
let childLeadsToViableHead = ? self.nodeLeadsToViableHead(child.get())
let # Aliases to the 3 possible (bestChild, bestDescendant) tuples
changeToNone = (none(Index), none(Index))
changeToChild = (
some(childIdx),
# Nim `options` module doesn't implement option `or`
if child.get().bestDescendant.isSome(): child.get().bestDescendant
else: some(childIdx)
)
noChange = (parent.get().bestChild, parent.get().bestDescendant)
# TODO: state-machine? The control-flow is messy
let (newBestChild, newBestDescendant) = block:
if parent.get().bestChild.isSome:
let bestChildIdx = parent.get().bestChild.unsafeGet()
if bestChildIdx == childIdx and not childLeadsToViableHead:
# The child is already the best-child of the parent
# but it's not viable to be the head block => remove it
changeToNone
elif bestChildIdx == childIdx:
# If the child is the best-child already, set it again to ensure
# that the best-descendant of the parent is up-to-date.
changeToChild
else:
let bestChild = self.nodes[bestChildIdx]
if bestChild.isNone():
return err ForkChoiceError(
kind: fcInvalidBestDescendant,
index: bestChildIdx)
let bestChildLeadsToViableHead =
? self.nodeLeadsToViableHead(bestChild.get())
if childLeadsToViableHead and not bestChildLeadsToViableHead:
# The child leads to a viable head, but the current best-child doesn't
changeToChild
elif not childLeadsToViableHead and bestChildLeadsToViableHead:
# The best child leads to a viable head, but the child doesn't
noChange
elif child.get().weight == bestChild.get().weight:
# Tie-breaker of equal weights by root
if child.get().root.tiebreak(bestChild.get().root):
changeToChild
else:
noChange
else: # Choose winner by weight
let cw = child.get().weight
let bw = bestChild.get().weight
if cw >= bw:
changeToChild
else:
noChange
else:
if childLeadsToViableHead:
# There is no current best-child and the child is viable
changeToChild
else:
# There is no current best-child but the child is not viable
noChange
self.nodes.buf[parentIdx - self.nodes.offset].bestChild = newBestChild
self.nodes.buf[parentIdx - self.nodes.offset].bestDescendant = newBestDescendant
ok()
func nodeLeadsToViableHead(self: ProtoArray, node: ProtoNode): FcResult[bool] =
## Indicates if the node itself or its best-descendant are viable
## for blockchain head
let bestDescendantIsViableForHead = block:
if node.bestDescendant.isSome():
let bestDescendantIdx = node.bestDescendant.unsafeGet()
let bestDescendant = self.nodes[bestDescendantIdx]
if bestDescendant.isNone:
return err ForkChoiceError(
kind: fcInvalidBestDescendant,
index: bestDescendantIdx)
self.nodeIsViableForHead(bestDescendant.get())
else:
false
ok(bestDescendantIsViableForHead or self.nodeIsViableForHead(node))
func nodeIsViableForHead(self: ProtoArray, node: ProtoNode): bool =
## This is the equivalent of `filter_block_tree` function in eth2 spec
## https://github.com/ethereum/consensus-specs/blob/v0.10.0/specs/phase0/fork-choice.md#filter_block_tree
##
## Any node that has a different finalized or justified epoch
## should not be viable for the head.
(
(node.justifiedCheckpoint == self.justifiedCheckpoint) or
(self.justifiedCheckpoint.epoch == Epoch(0))
) and (
(node.finalizedCheckpoint == self.finalizedCheckpoint) or
(self.finalizedCheckpoint.epoch == Epoch(0))
)
# Sanity checks
# ----------------------------------------------------------------------
# Sanity checks on internal private procedures
when isMainModule:
import nimcrypto/hash
echo "Sanity checks on fork choice tiebreaks"
block:
const a = Eth2Digest.fromHex("0x0000000000000001000000000000000000000000000000000000000000000000")
const b = Eth2Digest.fromHex("0x0000000000000000000000000000000000000000000000000000000000000000") # sha256(1)
doAssert tiebreak(a, b)
block:
const a = Eth2Digest.fromHex("0x0000000000000002000000000000000000000000000000000000000000000000")
const b = Eth2Digest.fromHex("0x0000000000000001000000000000000000000000000000000000000000000000") # sha256(1)
doAssert tiebreak(a, b)
block:
const a = Eth2Digest.fromHex("0xD86E8112F3C4C4442126F8E9F44F16867DA487F29052BF91B810457DB34209A4") # sha256(2)
const b = Eth2Digest.fromHex("0x7C9FA136D4413FA6173637E883B6998D32E1D675F88CDDFF9DCBCF331820F4B8") # sha256(1)
doAssert tiebreak(a, b)