https://github.com/bsv-blockchain/go-teranode-p2p-client
Go library for connecting to Teranode's P2P gossip network as a client/subscriber
https://github.com/bsv-blockchain/go-teranode-p2p-client
bitcoin bitcoinsv bsv golang p2p teranode
Last synced: 3 months ago
JSON representation
Go library for connecting to Teranode's P2P gossip network as a client/subscriber
- Host: GitHub
- URL: https://github.com/bsv-blockchain/go-teranode-p2p-client
- Owner: bsv-blockchain
- License: other
- Created: 2025-12-12T18:57:39.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T14:24:09.000Z (4 months ago)
- Last Synced: 2026-03-31T16:28:37.751Z (4 months ago)
- Topics: bitcoin, bitcoinsv, bsv, golang, p2p, teranode
- Language: Go
- Homepage:
- Size: 657 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
- Support: .github/SUPPORT.md
- Agents: .github/AGENTS.md
Awesome Lists containing this project
README
# 🛰 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](https://golang.org/doc/devel/release.html#policy).
```shell script
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](https://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` |
| `NetworkRegtest` | `regtest` |
> **Note:** `NetworkTeratestnet` and `NetworkRegtest` require 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
```go
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](https://github.com/mrz1836/mage-x) build tool for development:
```shell script
go install github.com/mrz1836/mage-x/cmd/magex@latest
```
View all build commands
```bash script
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 →](.github/docs/repository-features.md)**
Library Deployment
This project uses [goreleaser](https://github.com/goreleaser/goreleaser) for streamlined binary and library deployment to GitHub. To get started, install it via:
```bash
brew install goreleaser
```
The release process is defined in the [.goreleaser.yml](.goreleaser.yml) configuration file.
Then create and push a new Git tag using:
```bash
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](.github/AGENTS.md) before every commit:
```bash
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/`](.github/env/README.md) and provides 17x faster execution than traditional Python-based pre-commit hooks. See the [complete documentation](http://github.com/mrz1836/go-pre-commit) for details.
GitHub Workflows
All workflows are driven by modular configuration in [`.github/env/`](.github/env/README.md) — no YAML editing required.
**[View all workflows and the control center →](.github/docs/workflows.md)**
Updating Dependencies
To update all dependencies (Go modules, linters, and related tools), run:
```bash
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](https://github.com/mrz1836/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](https://github.com/bsv-blockchain/go-teranode-p2p-client/actions) and use [Go version 1.26.x](https://go.dev/doc/go1.26). View the [configuration file](.github/workflows/fortress.yml).
Run all tests (fast):
```bash script
magex test
```
Run all tests with race detector (slower):
```bash script
magex test:race
```
## ⚡ Benchmarks
Run the Go benchmarks:
```bash script
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](.github/CODE_STANDARDS.md).
## 🤖 AI Usage & Assistant Guidelines
Read the [AI Usage & Assistant Guidelines](.github/tech-conventions/ai-compliance.md) for details on how AI is used in this project and how to interact with AI assistants.
## 👥 Maintainers
| [
](https://github.com/icellan) | [
](https://github.com/galt-tr) | [
](https://github.com/mrz1836) |
|:--------------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------:|
| [Siggi](https://github.com/icellan) | [Dylan](https://github.com/galt-tr) | [MrZ](https://github.com/mrz1836) |
## 🤝 Contributing
View the [contributing guidelines](.github/CONTRIBUTING.md) and please follow the [code of conduct](.github/CODE_OF_CONDUCT.md).
### How can I help?
All kinds of contributions are welcome :raised_hands:!
The most basic way to show your support is to star :star2: the project, or to raise issues :speech_balloon:.
[](https://github.com/bsv-blockchain/go-teranode-p2p-client/stargazers)
## 📝 License
[](LICENSE)