Solana Gossip Slot Printer (Go)

This repository has one goal: connect to Solana gossip and print observed slots.

Everything else in the codebase (handshake, packet decode, CRDS handling, logging) exists only to support that slot-printing workflow.

IMPORTANT The dto/model.go and dto/model_test.go were initally writting by me, but got tired of errors in https://github.com/gagliardetto/binary lib and the lack of documentation by agave source code, that I end up using AI for it. Be ready to read a bunch of "working" code that just looks messy. Also due to this we are using a forked version of gaglardetto/binary lib which fix the bin:"optional" tag.

What It Does

• Connects to Solana gossip entrypoints.
• Performs TCP IP echo handshake and starts UDP gossip flow.
• Receives gossip traffic and extracts slot-related data.
• Prints slots observed from gossip messages.
• Logs runtime and decode issues to stdout and a file via zerolog.

Repository Layout

• runtime/: executable entrypoint (main.go).
• services/: gossip service runtime logic, networking, CRDS state.
• dto/: protocol and CRDS wire model encode/decode definitions.
• .env.example: basic environment variable template.

Requirements

• Go 1.25.5 (as declared in go.mod).
• You'll need to open the TPC and UDP ports you specified in .env.

Quick Start

1. Clone and enter the repository.
2. Copy env file:

cp .env.example .env

3. (Optional) adjust ports and environment in .env.
4. Run:

go run ./runtime/main.go

On first start, if id.json is not found, a new keypair is generated and stored locally.

Run Locally with solana-test-validator

Use this when you want to test slot printing without connecting to public clusters.

1. Start a local validator with gossip on 127.0.0.1:8001:

RUST_LOG=solana_gossip=info ./target/release/solana-test-validator --reset --ledger /tmp/solana-test-ledger --gossip-port 8001 --rpc-port 8899 --limit-ledger-size 5

NOTE: Assumes you compile solana-test-validator with cargo build --release --bin solana-test-validator, I think if you have solana-cli installed you already haave solana-test-validator, not sure tbh.

2. In this repository, create/update .env for local mode:

UDP_PORT=9005
TCP_PORT=9005
LOG_LEVEL=info
LOG_FILE=gossip.log
# Leave ENV unset for local mode (or set to any value other than testnet/mainnet)

NOTE: if you run solana-test-validator make sure these UDP/TCP ports are not already bind by solana-testnet-validator.

3. Start the slot printer in a second terminal:

go run ./runtime/main.go

If everything is wired correctly, you should see the process receive gossip traffic and print observed slots.

Configuration

Loaded from .env by runtime/main.go.

Network and Service

• UDP_PORT (default 8001)
• TCP_PORT (default 8001)
• ENV
  • testnet -> testnet entrypoints
  • mainnet -> mainnet-beta entrypoints
  • anything else (or unset) -> local entrypoint 127.0.0.1:8001

Slot Display

• DISPLAY_SLOTS: set to true to print observed slots to stdout (default: disabled)

Logging

• LOG_LEVEL: trace, debug, info (default), or error
• LOG_FILE: output file path (default gossip.log)

Logs are written to both stdout and LOG_FILE.

Example .env

UDP_PORT=9005
TCP_PORT=9005
ENV=testnet
LOG_LEVEL=info
LOG_FILE=gossip.log
DISPLAY_SLOTS=true

Scope

This project is intentionally narrow:

• It is not a validator.
• It is not a full gossip implementation for production operations.
• It is not meant to index or persist the full CRDS state.

The target outcome is simply to observe and print slot updates from live gossip traffic.

Wire Compatibility Notes

Because slot data is extracted from gossip packets, wire compatibility still matters for decoding correctness.

The module uses:

• github.com/gagliardetto/solana-go
• a replaced binary package in go.mod: github.com/gagliardetto/binary => github.com/Gealber/binary

Several CRDS payloads with vector fields use explicit marshal/unmarshal logic to match on-wire layout and avoid decode drift.

Troubleshooting

unknown CrdsData discriminant: <large_number>

This usually indicates byte offset drift while decoding an earlier field in the same packet, not a new/unsupported CRDS variant.

What to check:

• Vector length prefixes are decoded exactly as expected by Solana wire format.
• Optional/tagged fields match Rust layout.
• Any recently changed DTO struct with slices or nested enums.

No gossip traffic

• Confirm ENV is set correctly.
• Confirm ports are open and not already in use.
• Confirm outbound access to Solana entrypoints.

Logging file not created

• Ensure process has write permission to the directory.
• If LOG_FILE includes a folder, runtime will attempt to create it.

Disclaimer

This is a narrow utility focused on printing slots from Solana gossip traffic.