ChainSafe / ChainSafe/lodestar
BeaconEngine
- Dominant language
- TypeScript
- Stars
- 1.4k
- Forks
- 483
- Avg merge
- 1d 16h
- Merged PRs (30d)
- 150
Description
### Problem description
Refactor the current BeaconChain to have a IBeaconEngine (JS today, could be swapped by a zig implementation later).
```
┌──────────── NETWORK ────────────┐ ┌──────────── SYNC ─────────────┐ ┌──────── API ────────┐
│ gossip · processor · reqresp · │ │ RangeSync · UnknownBlockInput ·│ │ beacon · validator ·│
│ peers · discv5 │ │ Backfill │ │ debug · events │
└───────────────┬─────────────────┘ └───────────────┬───────────────┘ └─────────┬───────────┘
validateGossip*(bytes)→verdict processChainSegment(blocks) produce* · duties ·
reqresp serve UnknownBlockInput → DA caches state reads · serve
│ │ │
▼ ▼ ▼
┌──────────────────────────── BeaconChain — facade (JS) ─────────────────────────────────────┐
│ orchestrate · emit events / SSE · peer scoring │
│ DataAvailabilityEngine: seenBlockInputCache · seenPayloadEnvelopeInputCache · getBlobs │
│ DA / light-client DB: blobs · columns · payloads │
│ │
│ ┌─────────────────────── BeaconEngine (JS ⇆ Zig) — the seam ──────────────────────────┐ │
│ │ state · fork choice · STF · regen · gossip validation · op pools · BLS · KZG · │ │
│ │ consensus seen-caches · OWNS blocks + states DB │ │
│ │ api: validateGossip* · verify/import · produce* · duties · forkChoiceRead · getState│ │
│ └─────────────────────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────┬───────────────────────────────┬──────────────────────────┘
│ newPayload · fcU · getPayload │ getBlobs
▼ ▼
ExecutionEngine ─────────────────────► Execution Layer
```
### Solution description
given the BeaconEngine above, all consumers should not query its data directly, instead of that, call apis of the IBeaconEngine
- gossip validation apis of IBeaconEngine
- BeaconState is private to BeaconEngine and should not be transferred around in the BeaconChain
- implement a subset of Forkchoice apis in BeaconEngine, all consumers should talk to BeaconEngine instead of querying forkchoice directly. Also forkchoice is not part of BeaconChain anymore.
- BeaconState + BeaconBlock are managed internally by BeaconEngine. When processing a finalized checkpoint, BeaconEngine should persist BeaconState + migrate blocks from hot db to cold db, while BeaconChain (the facade, js side) migrates remaining data
this is what we have in the meeting
[zig_roadmap_slides.pdf](https://github.com/user-attachments/files/28939831/zig_roadmap_slides.pdf)
### Additional context
- the refactor should not affect the current beacon node. We just make it ready for the next integation to lodestar-z
- the BeaconStateView abstraction is not touched, it's still the 1st integration point we have with lodestar-z, see also #8650
- a binding layer to lodestar-z needs to be implemented. There will be a little overhead calling it, but there should be improvement due to BLS verification happened there
Contributor guide
Assessment
This issue has not been assessed yet.