Skip to content

implement prune backoff for v1.1 spec#111

Open
bomanaps wants to merge 7 commits intozen-eth:mainfrom
bomanaps:feat/gossipsub
Open

implement prune backoff for v1.1 spec#111
bomanaps wants to merge 7 commits intozen-eth:mainfrom
bomanaps:feat/gossipsub

Conversation

@bomanaps
Copy link
Copy Markdown
Contributor

Add GossipSub v1.1 Prune Backoff

Implements the prune backoff mechanism from the GossipSub v1.1 spec. This prevents peers from re-grafting to mesh topics immediately after being pruned, reducing unnecessary churn and potential spam.

@bomanaps bomanaps requested a review from GrapeBaBa February 10, 2026 10:27
@gemini-code-assist
Copy link
Copy Markdown

Summary of Changes

Hello @bomanaps, I'm Gemini Code Assist1! 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 integrates the GossipSub v1.1 prune backoff mechanism, a critical enhancement for improving the stability and resilience of the pubsub network. The primary goal is to prevent rapid re-grafting by peers after they have been pruned, which helps in mitigating network churn and potential abuse. The implementation involves tracking backoff states for peers, enforcing these states during graft attempts, and ensuring that prune messages correctly communicate backoff durations, thereby aligning the system with the latest protocol specification.

Highlights

  • GossipSub v1.1 Prune Backoff Implementation: Implemented the GossipSub v1.1 prune backoff mechanism to prevent peers from immediately re-grafting to topics after being pruned, reducing network churn and potential spam.
  • Backoff State Tracking: Introduced a backoff hash map within the Gossipsub struct to track peers that are in a backoff period for specific topics, along with their expiration timestamps.
  • Configuration Options: Added new configuration options such as prune_backoff_s, unsubscribe_backoff_s, backoff_slack_s, and gossipsub_v1_1 to control the backoff behavior and enable the v1.1 features.
  • Graft Handling with Backoff: Modified the handleGraft function to check if an incoming graft request is from a peer currently in backoff. Such requests are rejected with a PRUNE message, and the peer's backoff period is extended.
  • Prune Message Processing: Updated the handlePrune function to correctly parse and store the backoff duration specified in incoming PRUNE messages, ensuring the local node respects the remote peer's backoff policy.
  • Backoff Management Functions: Added utility functions (addBackoff, inBackoff, cleanupBackoffForTopic, cleanupExpiredBackoffs) to manage the lifecycle of backoff entries, including adding new entries, checking status, and removing expired ones.
  • Outgoing Prune Message Enhancement: Ensured that PRUNE messages sent by the local node now include the backoff duration as per the v1.1 specification, and the pruned peer is also added to the local backoff tracking.
  • Heartbeat Integration: Integrated the cleanupExpiredBackoffs function into the heartbeat mechanism for periodic maintenance and added a check to prevent grafting peers that are currently in backoff during heartbeat processing.
  • Git Ignore Update: Updated the .gitignore file to include new Zig build and package directories, improving repository cleanliness.

🧠 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.

Changelog
  • .gitignore
    • Added zig-cache/ to ignore Zig build cache directories.
    • Added zig-pkg/ to ignore Zig package directories.
  • src/protocols/pubsub/routers/gossipsub.zig
    • Added a backoff field to the Gossipsub struct to store topic-peer backoff timestamps.
    • Introduced prune_backoff_s, unsubscribe_backoff_s, backoff_slack_s, and gossipsub_v1_1 options to configure backoff behavior.
    • Implemented cleanup logic for the backoff hash map in the deinit function.
    • Modified handleGraft to check if a peer is in backoff and reject graft requests, extending the backoff period if necessary.
    • Updated handlePrune to record the backoff duration specified in incoming PRUNE messages.
    • Added addBackoff to store backoff entries, inBackoff to check backoff status, cleanupBackoffForTopic to remove expired backoffs for a topic, and cleanupExpiredBackoffs to remove all expired backoffs.
    • Updated sendPrune to include the backoff field in the PRUNE control message and to add the pruned peer to the local backoff tracking.
    • Refactored control message creation into a new makeControlMessage function to handle v1.1 specific fields.
    • Integrated cleanupExpiredBackoffs into the heartbeat function to periodically clear old backoff entries.
    • Added a check in heartbeat to prevent grafting peers that are currently in backoff.
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.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. 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.

Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request implements the prune backoff mechanism from the GossipSub v1.1 specification. While the overall approach for handling backoffs, including GRAFT messages and backoff information in PRUNE messages, is sound, a high-severity security vulnerability was identified. Specifically, the handling of incoming PRUNE messages allows an untrusted backoff value to cause an integer overflow and a process panic, leading to a Denial of Service. Furthermore, a critical memory safety issue exists in the backoff cleanup logic that could lead to a use-after-free. There are also medium-severity issues related to code duplication and a redundant entry in the .gitignore file. Addressing these points will significantly improve the robustness and security of the code.

Comment thread src/protocols/pubsub/routers/gossipsub.zig
Comment thread src/protocols/pubsub/routers/gossipsub.zig
Comment thread .gitignore Outdated
Comment on lines +2363 to +2381
// GossipSub v1.1: Include backoff duration in PRUNE message
if (self.opts.gossipsub_v1_1) {
prune_msg[0] = .{
.topic_i_d = topic,
.backoff = self.opts.prune_backoff_s,
.peers = null, // TODO: Implement peer exchange (PX)
};

// Also add backoff for ourselves (both sides must respect backoff per spec)
const now_ms = std.time.milliTimestamp();
const backoff_until_ms = now_ms + @as(i64, @intCast(self.opts.prune_backoff_s * 1000));
self.addBackoff(topic, to.*, backoff_until_ms) catch |err| {
std.log.warn("failed to add backoff when pruning peer {} on topic {s}: {}", .{ to.*, topic, err });
};
} else {
prune_msg[0] = .{
.topic_i_d = topic,
};
}
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This block duplicates the logic for creating a v1.1 PRUNE message and adding a backoff, which is also present in the makeControlMessage function. To improve maintainability and avoid code duplication, you can refactor this to use the makeControlMessage helper function.

        prune_msg[0] = self.makeControlMessage(rpc.ControlPrune, topic, to.*);

@bomanaps bomanaps changed the title feat(gossipsub): implement prune backoff for v1.1 spec implement prune backoff for v1.1 spec Feb 10, 2026
@GrapeBaBa
Copy link
Copy Markdown
Member

@bomanaps can it be tested in a specific test?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants