feat: add Zig peer manager module with NAPI bindings by nazarhussain · Pull Request #308 · ChainSafe/lodestar-z

nazarhussain · 2026-04-07T14:23:35Z

Summary

Implement peer management logic engine in Zig (store, scoring, prioritization, relevance)
Line-by-line port of packages/beacon-node/src/network/peers from Lodestar TS
Expose via NAPI bindings as a tick-driven stateful module (no internal threads)
Designed to work standalone for the eventual native client

Architecture

Layered modules in src/peer_manager/:

store.zig — StringHashMap-backed peer data storage
scorer.zig — RPC score tracking with exponential decay, gossipsub blending, reconnection cooldowns
prioritize.zig — subnet-aware peer connect/disconnect algorithm (PeerDAS custody groups, attestation/sync subnets)
relevance.zig — fork digest, clock, finalized root validation
manager.zig — orchestrator composing all layers, returns Action[] for caller dispatch

NAPI bindings in bindings/napi/peer_manager.zig with 23 exported functions.

Test plan

58 Zig unit tests across all layers (zig build test:peer_manager)
TypeScript integration tests (bindings/test/peerManager.test.ts) — requires NAPI build
Side-by-side testnet validation with TS implementation

Current Architecture

Zig Transition Architecture

gemini-code-assist · 2026-04-07T14:24:00Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses critical stability and compatibility issues within the peerManager module. By hardening the NAPI boundary, improving memory management for discovery payloads, and aligning the API contract with Lodestar expectations, the changes ensure more robust peer management. Additionally, the introduction of explicit TypeScript definitions improves the maintainability and usability of the binding surface.

Highlights

Lodestar Action Compatibility: Added parseExternalPeerActionName() to support Lodestar-style action names (e.g., MidToleranceError) alongside existing Zig enum tags, improving API compatibility.
Memory Safety: Resolved memory lifetime issues by moving discovery query buffers onto the PeerManager and ensuring peer IDs are properly duplicated within NAPI callbacks, preventing use-after-free errors.
TypeScript Definitions: Added comprehensive TypeScript definitions for the peerManager API, including configuration, metadata, and action types, enhancing developer experience and type safety.
Metadata Plumbing: Updated the NAPI boundary to correctly parse and pass custodyGroups and samplingGroups metadata from JavaScript to the Zig peer manager.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a comprehensive PeerManager implementation in Zig, including NAPI bindings for Node.js integration. The system manages peer lifecycles, scoring with exponential decay, and subnet-aware prioritization. The review feedback focuses on aligning error handling with the repository's fail-fast style guide by treating out-of-memory conditions as fatal and optimizing HashMap operations in the PeerStore to avoid redundant lookups.

gemini-code-assist · 2026-04-07T14:26:26Z

+        ) catch |err| switch (err) {
+            error.PeerAlreadyExists => return self.actions.items,
+            error.OutOfMemory => return err,
+        };


The error handling here is redundant. store.addPeer only returns error.PeerAlreadyExists or error.OutOfMemory. Since error.OutOfMemory is a fatal error that should crash the program (per the style guide), you can simplify this to try self.store.addPeer(...) and let the caller handle the OOM or let it propagate.

try self.store.addPeer(peer_id, direction, self.clock_fn(), self.config);

References

Assertions and error handling: The style guide mandates that assertion failures (and by extension, unrecoverable errors like OOM) should crash the program to downgrade catastrophic bugs into liveness bugs.

gemini-code-assist · 2026-04-07T14:26:26Z

+        const owned_key = try self.allocator.dupe(u8, peer_id);
+        errdefer self.allocator.free(owned_key);


The errdefer block here is good, but owned_key is not actually used if put fails. It is better to perform the allocation only after confirming the peer does not exist, or use getOrPut to avoid double-lookup.

const result = try self.peers.getOrPut(peer_id); if (result.found_existing) return error.PeerAlreadyExists; const owned_key = try self.allocator.dupe(u8, peer_id); errdefer self.allocator.free(owned_key); result.key_ptr.* = owned_key;

References

Efficiency: Avoid redundant lookups in HashMaps by using getOrPut.

Design spec for the Zig peer manager module covering all three delivery phases: PeerStore, PeerScorer, and full PeerManager. Includes TS source reference archive from Lodestar unstable branch. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

- BLOCK-1: Fix checkPingAndStatus — use initial timestamp trick for inbound grace period instead of fabricated disconnect check - BLOCK-2: onConnectionOpen emits send_ping + send_status for outbound - BLOCK-3: onConnectionClose applies cooldown for inbound peers - BLOCK-4: addPeer takes Config for direction-dependent timestamps - FLAG-1: Add HEARTBEAT_INTERVAL_MS and CHECK_PING_STATUS_INTERVAL - FLAG-2: Add negative_gossip_score_ignore_threshold to Config - FLAG-3: Document gossipsub weight derivation formula - FLAG-4: onStatusReceived takes current_slot parameter - FLAG-5: Remove incorrect cooldown from onGoodbye - FLAG-6: Add getGossipScore accessor to PeerScorer - FLAG-7: Fix misleading "prune after decay" comment - NOTE-3: Clarify StatusScore values in sort description - NOTE-5: Move emit_peer_connected to onStatusReceived Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

10 tasks across 6 chunks: types/constants, PeerStore, PeerScorer, relevance + prioritization, PeerManager orchestrator, NAPI bindings + TS integration tests. Bottom-up build order with TDD approach. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

…vals Port all score thresholds, peer manager intervals, and prioritization constants from the TypeScript implementation. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Port all shared enums, structs, action types, config, and bitvector helpers from the TypeScript peer manager implementation. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Create module entry point with re-exports and register peer_manager module and test step in the build system. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

…d cooldowns Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

…lidation Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

…connect logic Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

…prioritization Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

….zig Add peer_manager to zbuild.zon modules and bindings library imports. Run zbuild sync to regenerate build.zig with correct registration. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Use 4 mid_tolerance reports (-20) instead of 10 (-50) to stay above the ban threshold, which would trigger a cooldown and block decay. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

@intcast

- Replace getValueUint64 with getValueInt64 + @intcast (zapi has no u64 getter) - Replace typeOf with typeof (zapi naming convention) Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

nazarhussain changed the title ~~[codex] Fix peerManager binding ownership and API compatibility~~ feat: add Zig peer manager module with NAPI bindings Apr 7, 2026

gemini-code-assist Bot reviewed Apr 7, 2026

View reviewed changes

nazarhussain and others added 20 commits April 14, 2026 11:54

feat(peer_manager): add constants.zig with score thresholds and inter…

f70bee5

…vals Port all score thresholds, peer manager intervals, and prioritization constants from the TypeScript implementation. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

feat(peer_manager): add types.zig with all shared types and helpers

e9bc9a1

Port all shared enums, structs, action types, config, and bitvector helpers from the TypeScript peer manager implementation. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

feat(peer_manager): add root.zig and register module in build.zig

2d7fe8a

Create module entry point with re-exports and register peer_manager module and test step in the build system. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

feat(peer_manager): add PeerStore with HashMap-backed peer data storage

e923c07

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

feat(peer_manager): add PeerScorer with decay, gossipsub blending, an…

357aca5

…d cooldowns Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

feat(peer_manager): add assertPeerRelevance with 4-check relevance va…

30837d6

…lidation Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

feat(peer_manager): add prioritizePeers with subnet-aware connect/dis…

e1fdea0

…connect logic Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

feat(peer_manager): add PeerManager orchestrating store, scorer, and …

d814397

…prioritization Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

feat(peer_manager): add NAPI bindings for peer manager

c1b990d

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

test(peer_manager): add TypeScript integration tests for NAPI bindings

318db58

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

chore: remove the unncessary docs

3c5b01c

fix(peer_manager): register module in zbuild.zon and regenerate build…

ecce100

….zig Add peer_manager to zbuild.zon modules and bindings library imports. Run zbuild sync to regenerate build.zig with correct registration. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

fix(peer_manager): fix scorer decay test hitting ban threshold

0065ed6

Use 4 mid_tolerance reports (-20) instead of 10 (-50) to stay above the ban threshold, which would trigger a cooldown and block decay. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

fix(peer_manager): fix NAPI bindings for zapi Value API

feb1b88

- Replace getValueUint64 with getValueInt64 + @intcast (zapi has no u64 getter) - Replace typeOf with typeof (zapi naming convention) Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

fix(peer-manager): accept Lodestar peer action names

b534d04

fix(peer-manager): retain discovery query payloads

85f656e

fix(bindings): harden peerManager NAPI surface

f1e8047

nazarhussain force-pushed the nh/peer-manager branch from 3acc71e to f1e8047 Compare April 14, 2026 09:56

nazarhussain added 6 commits April 14, 2026 11:56

chore: update peer-manage build

bc4be0c

chore: fix the zapi import path

69dd58a

fix(peer_manager): simplify onConnectionOpen error handling

10ccab3

refactor(peer_manager): use getOrPut in addPeer for efficiency

98542d3

fix(peer_manager): correct detectStarvation logic

f4ed937

fix(peer_manager): apply reconnection cooldown onGoodbye

0aa82d6

chore: add missing interfaces for the PeerStore

f01ed53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add Zig peer manager module with NAPI bindings#308

feat: add Zig peer manager module with NAPI bindings#308
nazarhussain wants to merge 27 commits intomainfrom
nh/peer-manager

nazarhussain commented Apr 7, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot commented Apr 7, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Apr 7, 2026

Uh oh!

gemini-code-assist Bot Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		const owned_key = try self.allocator.dupe(u8, peer_id);
		errdefer self.allocator.free(owned_key);

Conversation

nazarhussain commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Architecture

Test plan

Current Architecture

Zig Transition Architecture

Uh oh!

gemini-code-assist Bot commented Apr 7, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

nazarhussain commented Apr 7, 2026 •

edited

Loading