Skip to content

BP Gossip Peering Instructions

Jump to bottom
Kevin Heifner edited this page May 27, 2025 · 4 revisions

Gossip-based BP Auto-Peering

Spring v1.2.0 includes a brand new p2p feature designed to automate peering between consensus nodes to reduce laborious manual configuration and make the network more resilient.

The benefits of gossip-based bp auto-peering are numerous:

  • Zero-touch connectivity: No more manually maintaining peer lists—nodes automatically discover and link to every active producer in the schedule.
  • Resilience to change: As new nodes join, upgrades roll out, or producer rankings shuffle, the mesh of connections between consensus nodes will self-heal and keep every finalizer and proposer connected.
  • Rapid DDoS recovery: If a node’s endpoint becomes unavailable or under attack, you can update its advertised address and peers will pick up the change via gossip instantly.
  • Secure, authenticated peering: On-chain “peer keys” ensure that connection details remain private, only shared with other trusted consensus nodes.
  • Operational automation: With a single HTTP call, you retrieve live peer endpoints for firewall updates.

High Level Overview of System

The new gossip-based auto-peering in Spring v1.2.0 works like this:

  • Each block producer calls regpeerkey to publish a public peer key tied to their account.
  • Each block producer updates their relay nodes configuration, adding p2p-bp-gossip-endpoint to specify their bp account, inbound endpoint, and outbound ip address
  • Relays only accept gossip from nodes with valid block producers
    • authenticated with a valid bp peer key.
    • Up to the top 50 bps by rank
      • Has vote power at least half of the vote power of the BP in rank 21
  • Every relay broadcasts gossip messages to communicate all of the bp endpoint information it is aware of via gossip
  • Nodeos automatically maintains P2P connections with each discovered producer in the top 21
  • As the producer schedule changes, new nodes spin up, or versions upgrade, gossip updates propagate
  • Nodes with firewall protections in place use /v1/net/bp_gossip_peers to dynamically update their firewall

Step by Step Setup Guide

Here’s a step-by-step guide for Node Operators to enable Gossip-Based Auto-Peering in Spring v1.2.0:

1. Generate a New Peer Key Pair

You need an EOS-compatible key pair that you’ll register on-chain and use on your canary relay node.

  1. On your operator machine, run: 
    cleos create key --to-console
  2. Save the output:
    • Public Key (e.g. EOS6y94JK7Dsg3iJCrnvdbyLPZJvaAhfBSU44eU8jkPd4VHX9CJzp)
    • Private Key (e.g. 5J6Z64Jqexample…)

Keep the private key secure—this is how your bp relay node will use to authenticate itself to other BPs when participating in gossip.

2. Register Your Peer Public Key On-Chain

Use the system contract’s regpeerkey action to tie your public key to your block‐producer account:

cleos push action eosio regpeerkey \
  '["<your_bp_account>","<your_public_key>"]' \
  -p <your_bp_account>@active
  • If you ever need to replace it, just call regpeerkey again with a new key.
  • To remove your key (e.g. when retiring a node), use: 
    cleos push action eosio delpeerkey \
  '["<your_bp_account>"]' \
  -p <your_bp_account>@active

3. Configure Your Spring Node

On each canary/relay node you use for inter-BP peering (often co-located with your producer/finalizer), add this configuration:

  --p2p-bp-gossip-endpoint arg          The BP account, inbound connection
                                        endpoint, outbound connection IP
                                        address. The BP account is the producer
                                        peer name to retrieve peer-key from
                                        on-chain peerkeys table registered
                                        on-chain via regpeerkey action. The
                                        inbound connection endpoint is
                                        typically the listen endpoint of this
                                        node. The outbound connection IP
                                        address is typically the IP address of
                                        this node. Peer will use this value to
                                        allow access through firewall. Private
                                        key of peer-key should be configured
                                        via signature-provider.
                                        
                                        Syntax: bp_account,inbound_endpoint,ou
                                        tbound_ip_address
                                        
                                        Example:
                                           myprod,myhostname.com:9876,198.51.10
                                        0.1
                                           myprod,myhostname2.com:9876,[2001:0d
                                        b8:85a3:0000:0000:8a2e:0370:7334]

Add the public/private key pair of the public key register above via regpeerkey as a signature-provider in the nodeos config.ini.

signature-provider = EOS6y94JK7Dsg3iJCrnvdbyLPZJvaAhfBSU44eU8jkPd4VHX9CJzp=KEY:5J6Z64Jqexample…

Note

Bootstrapping Gossip: You need to manually configure at least one “bootstrap” peer already in the gossip network so your node can join the gossip network—once connected to one, your node will learn all the other peers automatically.

Clone this wiki locally