blockblaz / blockblaz/zeam

BeamNode mutex serializes chain work; heavy STF blocks interval vs gossip

Open
#786 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
Zig
Stars
97
Forks
39
PR merge metrics
No merged PRs in 30d

Description

## Summary

`BeamNode` uses a single `std.Thread.Mutex` to serialize work between the libxev main thread (`onInterval`) and the libp2p callback path (`onGossip`, `onReqRespResponse`, and locked sections of `onReqRespRequest`). Gossip handlers take the lock for the entire `chain.onGossip` path.

The Rust libp2p runtime runs on a dedicated OS thread, but **consensus CPU (state transition, verification, fork-choice updates) runs synchronously inside Zig callbacks while holding that mutex**. There is no separate worker pool for compute-heavy chain steps.

## Why it matters

Under CPU pressure (e.g. hash-sig verification, large blocks, deep fork-choice work), long critical sections can:

- stall `onInterval` while gossip holds the lock (or the reverse), worsening wall-clock vs head lag;
- contribute to RPC/gossip backpressure and timeouts observed on multi-client devnets.

## References (code)

- `pkgs/node/src/node.zig`: comment on `mutex` (serializes libxev main thread vs libp2p worker); `onGossip` locks before `chain.onGossip`; `onInterval` locks around `chain.onInterval`.
- `pkgs/network/src/ethlibp2p.zig`: dedicated thread for Rust network (`createAndRunNetworkThread`).

Fork choice has its own `RwLock` / `Mutex`, but that is orthogonal to this coarse `BeamNode` serialization.

## Suggested directions (for discussion)

- Shorten critical sections (e.g. parse/validate under lock, defer heavy work to a bounded queue + worker thread(s) with clear ordering rules).
- Or document this as an intentional invariant and tune timeouts / queue sizes accordingly.

## Context

Observed when analyzing devnet behavior: network and slot progression compete for the same lock while verification is expensive.

Contributor guide

No contributing guide indexed for this repository

Research direction

Read the mutex comment and callback implementations in pkgs/node/src/node.zig, especially onInterval, onGossip, onReqRespResponse, and onReqRespRequest. Then inspect createAndRunNetworkThread in pkgs/network/src/ethlibp2p.zig; the issue needs an agreed direction before work can be considered done, either reducing the critical sections with ordering guarantees or documenting and tuning the existing invariant.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust, zig
Domain
backend, networking, performance
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.