🛰  go-teranode-p2p-client

Go library for connecting to Teranode's P2P gossip network as a client/subscriber.

CI / CD		Quality
Security		Community

Project Navigation

📦 Installation	🧪 Examples & Tests	📚 Documentation
🛠️ Code Standards	⚡ Benchmarks	🤖 AI Usage
🤝 Contributing	👥 Maintainers	⚖️ License

📦 Installation

go-teranode-p2p-client requires a supported release of Go.

go get -u github.com/bsv-blockchain/go-teranode-p2p-client

📚 Documentation

• API Reference – Dive into the godocs at pkg.go.dev/github.com/bsv-blockchain/go-teranode-p2p-client

Features

• Re-exports canonical message types from Teranode's P2P package
• Embedded bootstrap peers for mainnet, testnet, and STN
• Persistent P2P identity (key management)
• Topic name helpers

Message Types

• BlockMessage - New block announcements
• SubtreeMessage - Transaction batch (subtree) announcements
• RejectedTxMessage - Rejected transaction notifications
• NodeStatusMessage - Node status updates

Topics

Constant	Topic Name
TopicBlock	block
TopicSubtree	subtree
TopicRejectedTx	rejected-tx
TopicNodeStatus	node_status

Use TopicName(network, topic) to construct full topic names (e.g., teranode/bitcoin/1.0.0/mainnet-block).

Networks

Constant	Network
NetworkMainnet	mainnet
NetworkTestnet	testnet
NetworkSTN	stn
NetworkTeratestnet	teratestnet

Note: NetworkTeratestnet requires manual bootstrap peer configuration via Config.MsgBus.BootstrapPeers.

Bootstrap Peers

Embedded bootstrap peers for main, test, and stn networks are automatically applied when using Config.Initialize().

Usage

package main

import (
    "context"
    "log/slog"
    "os"
    "os/signal"
    "syscall"

    p2pclient "github.com/bsv-blockchain/go-teranode-p2p-client"
)

func main() {
    // Create a context that cancels on interrupt signals
    ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer cancel()

    // Configure the P2P client
    cfg := p2pclient.Config{
        Network:     "main",   // Options: "main", "test", "stn"
        StoragePath: "./data", // Persistent storage for keys and peer cache
    }

    // Initialize the client (loads/generates P2P identity, connects to bootstrap peers)
    client, err := cfg.Initialize(ctx, "my-app")
    if err != nil {
        slog.Error("failed to initialize P2P client", slog.String("error", err.Error()))
        os.Exit(1)
    }
    defer client.Close()

    slog.Info("connected to Teranode P2P network",
        slog.String("peer_id", client.GetID()),
        slog.String("network", client.GetNetwork()),
    )

    // Subscribe to block announcements (returns typed channel)
    blocks := client.SubscribeBlocks(ctx)

    for block := range blocks {
        slog.Info("new block",
            slog.Uint64("height", uint64(block.Height)),
            slog.String("hash", block.Hash),
        )
    }
}

Development Build Commands

Get the MAGE-X build tool for development:

go install github.com/mrz1836/mage-x/cmd/magex@latest

View all build commands

magex help

Repository Features

This repository includes 25+ built-in features covering CI/CD, security, code quality, developer experience, and community tooling.

View the full Repository Features list →

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump push=true bump=patch branch=main

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Pre-commit Hooks

Set up the Go-Pre-commit System to run the same formatting, linting, and tests defined in AGENTS.md before every commit:

go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
go-pre-commit install

The system is configured via modular env files in .github/env/ and provides 17x faster execution than traditional Python-based pre-commit hooks. See the complete documentation for details.

GitHub Workflows

All workflows are driven by modular configuration in .github/env/ — no YAML editing required.

View all workflows and the control center →

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any tools managed by MAGE-X. It is the recommended way to keep your development environment and CI in sync with the latest versions.

🧪 Examples & Tests

All unit tests and examples run via GitHub Actions and use Go version 1.25.x. View the configuration file.

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

⚡ Benchmarks

Run the Go benchmarks:

magex bench

Note: Comprehensive benchmarks for P2P operations (peer discovery, message throughput, connection establishment) are planned for future releases. The current focus is on correctness and stability of the networking implementation.

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Usage & Assistant Guidelines

Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with AI assistants.

👥 Maintainers

Siggi	Dylan	MrZ

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬.

📝 License