nimbus-eth2/beacon_chain/gossip_processing/light_client_processor.nim

414 lines
14 KiB
Nim

# beacon_chain
# Copyright (c) 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
stew/objects,
chronos, metrics,
../spec/datatypes/altair,
../spec/light_client_sync,
../consensus_object_pools/block_pools_types,
".."/[beacon_clock, sszdump],
"."/[eth2_processor, gossip_validation]
export sszdump, eth2_processor, gossip_validation
# Light Client Processor
# ------------------------------------------------------------------------------
# The light client processor handles received light client objects
declareHistogram light_client_store_object_duration_seconds,
"storeObject() duration", buckets = [0.25, 0.5, 1, 2, 4, 8, Inf]
type
GetTrustedBlockRootCallback* =
proc(): Option[Eth2Digest] {.gcsafe, raises: [Defect].}
VoidCallback* =
proc() {.gcsafe, raises: [Defect].}
LightClientProcessor* = object
## This manages the processing of received light client objects
##
## from:
## - Gossip:
## - `LightClientFinalityUpdate`
## - `LightClientOptimisticUpdate`
## - `LightClientManager`:
## - `GetLightClientBootstrap`
## - `LightClientUpdatesByRange`
## - `GetLightClientFinalityUpdate`
## - `GetLightClientOptimisticUpdate`
##
## are then verified and added to:
## - `LightClientStore`
##
## The processor will also attempt to force-update the light client state
## if no update seems to be available on the network, that is both signed by
## a supermajority of sync committee members and also improves finality.
## This logic is triggered if there is no progress for an extended period
## of time, and there are repeated messages indicating that this is the best
## available data on the network during that time period.
# Config
# ----------------------------------------------------------------
dumpEnabled: bool
dumpDirInvalid: string
dumpDirIncoming: string
# Consumer
# ----------------------------------------------------------------
store: ref Option[LightClientStore]
getBeaconTime: GetBeaconTimeFn
getTrustedBlockRoot: GetTrustedBlockRootCallback
onStoreInitialized, onFinalizedHeader, onOptimisticHeader: VoidCallback
cfg: RuntimeConfig
genesis_validators_root: Eth2Digest
lastProgressTick: BeaconTime # Moment when last update made progress
lastDuplicateTick: BeaconTime # Moment when last duplicate update received
numDuplicatesSinceProgress: int # Number of duplicates since last progress
const
# These constants have been chosen empirically and are not backed by spec
duplicateRateLimit = chronos.seconds(5) # Rate limit for counting duplicates
duplicateCountDelay = chronos.minutes(15) # Delay to start counting duplicates
minForceUpdateDelay = chronos.minutes(30) # Minimum delay until forced-update
minForceUpdateDuplicates = 100 # Minimum duplicates until forced-update
# Initialization
# ------------------------------------------------------------------------------
proc new*(
T: type LightClientProcessor,
dumpEnabled: bool,
dumpDirInvalid, dumpDirIncoming: string,
cfg: RuntimeConfig,
genesis_validators_root: Eth2Digest,
store: ref Option[LightClientStore],
getBeaconTime: GetBeaconTimeFn,
getTrustedBlockRoot: GetTrustedBlockRootCallback,
onStoreInitialized: VoidCallback = nil,
onFinalizedHeader: VoidCallback = nil,
onOptimisticHeader: VoidCallback = nil
): ref LightClientProcessor =
(ref LightClientProcessor)(
dumpEnabled: dumpEnabled,
dumpDirInvalid: dumpDirInvalid,
dumpDirIncoming: dumpDirIncoming,
store: store,
getBeaconTime: getBeaconTime,
getTrustedBlockRoot: getTrustedBlockRoot,
onStoreInitialized: onStoreInitialized,
onFinalizedHeader: onFinalizedHeader,
onOptimisticHeader: onOptimisticHeader,
cfg: cfg,
genesis_validators_root: genesis_validators_root
)
# Storage
# ------------------------------------------------------------------------------
proc dumpInvalidObject(
self: LightClientProcessor,
obj: SomeLightClientObject) =
if self.dumpEnabled:
dump(self.dumpDirInvalid, obj)
proc dumpObject[T](
self: LightClientProcessor,
obj: SomeLightClientObject,
res: Result[T, BlockError]) =
if self.dumpEnabled and res.isErr:
case res.error
of BlockError.Invalid:
self.dumpInvalidObject(obj)
of BlockError.MissingParent:
dump(self.dumpDirIncoming, obj)
else:
discard
proc tryForceUpdate(
self: var LightClientProcessor,
wallTime: BeaconTime) =
## Try to force-update to the next sync committee period.
let
wallSlot = wallTime.slotOrZero()
store = self.store
if store[].isSome:
case store[].get.try_light_client_store_force_update(wallSlot)
of NoUpdate:
discard
of DidUpdateWithoutSupermajority:
warn "Light client force-updated without supermajority",
finalizedSlot = store[].get.finalized_header.slot,
optimisticSlot = store[].get.optimistic_header.slot
of DidUpdateWithoutFinality:
warn "Light client force-updated without finality proof",
finalizedSlot = store[].get.finalized_header.slot,
optimisticSlot = store[].get.optimistic_header.slot
proc processObject(
self: var LightClientProcessor,
obj: SomeLightClientObject,
wallTime: BeaconTime): Result[void, BlockError] =
let
wallSlot = wallTime.slotOrZero()
store = self.store
res =
when obj is altair.LightClientBootstrap:
if store[].isSome:
err(BlockError.Duplicate)
else:
let trustedBlockRoot = self.getTrustedBlockRoot()
if trustedBlockRoot.isNone:
err(BlockError.MissingParent)
else:
let initRes =
initialize_light_client_store(trustedBlockRoot.get, obj)
if initRes.isErr:
err(initRes.error)
else:
store[] = some(initRes.get)
ok()
elif obj is SomeLightClientUpdate:
if store[].isNone:
err(BlockError.MissingParent)
else:
store[].get.process_light_client_update(
obj, wallSlot, self.cfg, self.genesis_validators_root)
self.dumpObject(obj, res)
if res.isErr:
when obj is altair.LightClientUpdate:
if store[].isSome and store[].get.best_valid_update.isSome:
# `best_valid_update` gets set when no supermajority / improved finality
# is available. In that case, we will wait for a better update that once
# again fulfills those conditions. If none is received within reasonable
# time, the light client store is force-updated to `best_valid_update`.
case res.error
of BlockError.Duplicate:
if wallTime >= self.lastDuplicateTick + duplicateRateLimit:
if self.numDuplicatesSinceProgress < minForceUpdateDuplicates:
if obj.matches(store[].get.best_valid_update.get):
self.lastDuplicateTick = wallTime
inc self.numDuplicatesSinceProgress
if self.numDuplicatesSinceProgress >= minForceUpdateDuplicates and
wallTime >= self.lastProgressTick + minForceUpdateDelay:
self.tryForceUpdate(wallTime)
self.lastProgressTick = wallTime
self.lastDuplicateTick = wallTime + duplicateCountDelay
self.numDuplicatesSinceProgress = 0
else: discard
return res
when obj is altair.LightClientBootstrap | altair.LightClientUpdate:
self.lastProgressTick = wallTime
self.lastDuplicateTick = wallTime + duplicateCountDelay
self.numDuplicatesSinceProgress = 0
res
proc storeObject*(
self: var LightClientProcessor,
src: MsgSource, wallTime: BeaconTime,
obj: SomeLightClientObject): Result[bool, BlockError] =
## storeObject is the main entry point for unvalidated light client objects -
## all untrusted objects pass through here. When storing an object, we will
## update the `LightClientStore` accordingly
let
startTick = Moment.now()
store = self.store
previousFinalized =
if store[].isSome:
store[].get.finalized_header
else:
BeaconBlockHeader()
previousOptimistic =
if store[].isSome:
store[].get.optimistic_header
else:
BeaconBlockHeader()
? self.processObject(obj, wallTime)
let
storeObjectTick = Moment.now()
storeObjectDur = storeObjectTick - startTick
light_client_store_object_duration_seconds.observe(
storeObjectDur.toFloatSeconds())
let objSlot =
when obj is altair.LightClientBootstrap:
obj.header.slot
elif obj is SomeLightClientUpdateWithFinality:
obj.finalized_header.slot
else:
obj.attested_header.slot
debug "LC object processed",
finalizedSlot = store[].get.finalized_header.slot,
optimisticSlot = store[].get.optimistic_header.slot,
kind = typeof(obj).name,
objectSlot = objSlot,
storeObjectDur
when obj is altair.LightClientBootstrap:
if self.onStoreInitialized != nil:
self.onStoreInitialized()
self.onStoreInitialized = nil
var didProgress = false
if store[].get.optimistic_header != previousOptimistic:
when obj isnot SomeLightClientUpdateWithFinality:
didProgress = true
if self.onOptimisticHeader != nil:
self.onOptimisticHeader()
if store[].get.finalized_header != previousFinalized:
didProgress = true
if self.onFinalizedHeader != nil:
self.onFinalizedHeader()
ok didProgress
# Enqueue
# ------------------------------------------------------------------------------
proc addObject*(
self: var LightClientProcessor,
src: MsgSource,
obj: SomeLightClientObject,
resfut: Future[Result[void, BlockError]] = nil) =
## Enqueue a Gossip-validated light client object for verification
# Backpressure:
# Only one object is validated at any time -
# Light client objects are always "fast" to process
# Producers:
# - Gossip:
# - `LightClientFinalityUpdate`
# - `LightClientOptimisticUpdate`
# - `LightClientManager`:
# - `GetLightClientBootstrap`
# - `LightClientUpdatesByRange`
# - `GetLightClientFinalityUpdate`
# - `GetLightClientOptimisticUpdate`
let
wallTime = self.getBeaconTime()
(afterGenesis, wallSlot) = wallTime.toSlot()
if not afterGenesis:
error "Processing LC object before genesis, clock turned back?"
quit 1
let res = self.storeObject(src, wallTime, obj)
if resfut != nil:
if res.isOk:
resfut.complete(Result[void, BlockError].ok())
else:
resfut.complete(Result[void, BlockError].err(res.error))
# Message validators
# ------------------------------------------------------------------------------
declareCounter lc_light_client_finality_updates_received,
"Number of valid LC finality updates processed by this LC"
declareCounter lc_light_client_finality_updates_dropped,
"Number of invalid LC finality updates dropped by this LC", labels = ["reason"]
declareCounter lc_light_client_optimistic_updates_received,
"Number of valid LC optimistic updates processed by this LC"
declareCounter lc_light_client_optimistic_updates_dropped,
"Number of invalid LC optimistic updates dropped by this LC", labels = ["reason"]
func toValidationError(
v: Result[bool, BlockError],
wallTime: BeaconTime): Result[void, ValidationError] =
if v.isOk:
let didProgress = v.get
if didProgress:
when v is SomeLightClientUpdate:
let
signature_slot = v.signature_slot
currentTime = wallTime + MAXIMUM_GOSSIP_CLOCK_DISPARITY
forwardTime = signature_slot.light_client_optimistic_update_time
if currentTime < forwardTime:
# [IGNORE] The `finality_update` / `optimistic_update` is received
# after the block at `signature_slot` was given enough time to
# propagate through the network.
return errIgnore(typeof(v).name & ": received too early")
ok()
else:
# [IGNORE] The `finality_update` / `optimistic_update`
# advances the `finalized_header` / `optimistic_header`
# of the local `LightClientStore`.
errIgnore(typeof(v).name & ": no significant progress")
else:
case v.error
of BlockError.Invalid:
# [REJECT] The `finality_update` / `optimistic_update` is valid.
errReject($v.error)
of BlockError.MissingParent, BlockError.UnviableFork, BlockError.Duplicate:
# [IGNORE] No other `finality_update` with a lower or equal
# `finalized_header.slot` / `attested_header.slot` was already
# forwarded on the network.
errIgnore($v.error)
# https://github.com/ethereum/consensus-specs/blob/vFuture/specs/altair/sync-protocol.md#light_client_finality_update
proc lightClientFinalityUpdateValidator*(
self: var LightClientProcessor, src: MsgSource,
finality_update: altair.LightClientFinalityUpdate
): Result[void, ValidationError] =
logScope:
finality_update
debug "LC finality update received"
let
wallTime = self.getBeaconTime()
r = self.storeObject(src, wallTime, finality_update)
v = r.toValidationError(wallTime)
if v.isOk():
trace "LC finality update validated"
lc_light_client_finality_updates_received.inc()
else:
debug "Dropping LC finality update", error = v.error
lc_light_client_finality_updates_dropped.inc(1, [$v.error[0]])
v
# https://github.com/ethereum/consensus-specs/blob/vFuture/specs/altair/sync-protocol.md#light_client_optimistic_update
proc lightClientOptimisticUpdateValidator*(
self: var LightClientProcessor, src: MsgSource,
optimistic_update: altair.LightClientOptimisticUpdate
): Result[void, ValidationError] =
logScope:
optimistic_update
debug "LC optimistic update received"
let
wallTime = self.getBeaconTime()
r = self.storeObject(src, wallTime, optimistic_update)
v = r.toValidationError(wallTime)
if v.isOk():
trace "LC optimistic update validated"
lc_light_client_optimistic_updates_received.inc()
else:
debug "Dropping LC optimistic update", error = v.error
lc_light_client_optimistic_updates_dropped.inc(1, [$v.error[0]])
v