https://github.com/bsv-blockchain/go-chaintracks
Real-time Bitcoin SV header orchestration in Go
https://github.com/bsv-blockchain/go-chaintracks
bitcoin bitcoinsv block-header blockchain bsv go headers
Last synced: 3 months ago
JSON representation
Real-time Bitcoin SV header orchestration in Go
- Host: GitHub
- URL: https://github.com/bsv-blockchain/go-chaintracks
- Owner: bsv-blockchain
- License: other
- Created: 2025-11-20T22:55:28.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2026-03-23T14:22:05.000Z (3 months ago)
- Last Synced: 2026-03-24T11:23:49.437Z (3 months ago)
- Topics: bitcoin, bitcoinsv, block-header, blockchain, bsv, go, headers
- Language: Go
- Homepage:
- Size: 61 MB
- Stars: 2
- Watchers: 0
- Forks: 3
- 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-chaintracks
**Real-time Bitcoin SV header orchestration in Go**
CI / CD
Quality
Security
Community
### Project Navigation
📦 Installation
📚 Documentation
🧪 Examples & Tests
🤝 Contributing
🛠️ Code Standards
⚡ Benchmarks
🤖 AI Usage
📝 License
👥 Maintainers
## 📦 Installation
**go-chaintracks** requires a [supported release of Go](https://golang.org/doc/devel/release.html#policy).
```shell script
go get -u github.com/bsv-blockchain/go-chaintracks
```
## 📚 Documentation
- **API Reference** – Dive into the godocs at [pkg.go.dev/github.com/bsv-blockchain/go-chaintracks](https://pkg.go.dev/github.com/bsv-blockchain/go-chaintracks)
### Features
- In-memory chain tracking with height and hash indexes
- Chainwork calculation and comparison
- Automatic orphan pruning (keeps last 100 blocks)
- P2P live sync with automatic updates
- Bootstrap sync from CDN or API sources
- REST API with v2 endpoints
- CDN server for hosting header files
- File-based persistence with metadata
- Docker support with docker-compose
### Architecture
- **ChainManager** - Main orchestrator for chain operations
- **BlockHeader** - Extends SDK header with height and chainwork
- **File I/O** - Local storage with seek-based updates
- **P2P Sync** - Live header updates via message bus
- **ChainTracker** - Implements go-sdk interface
Usage as a Library
```go
import "github.com/bsv-blockchain/go-chaintracks/chaintracks"
// Create chain manager with local storage
// Network options: "main", "test", "teratest"
// Optional bootstrap URL for initial sync
cm, err := chaintracks.NewChainManager("main", "~/.chaintracks", "https://node.example.com")
if err != nil {
log.Fatal(err)
}
// Start P2P sync for automatic updates
ctx := context.Background()
tipChanges, err := cm.Start(ctx)
if err != nil {
log.Fatal(err)
}
// Listen for tip changes (optional)
go func() {
for tip := range tipChanges {
log.Printf("New tip: height=%d hash=%s", tip.Height, tip.Hash())
}
}()
// Query methods
tip := cm.GetTip()
height := cm.GetHeight()
header, err := cm.GetHeaderByHeight(123456)
header, err := cm.GetHeaderByHash(&hash)
// Cleanup
defer cm.Stop()
```
Usage as a Client
```go
import "github.com/bsv-blockchain/go-chaintracks/pkg/chaintracks"
// Connect to remote chaintracks server
client := chaintracks.NewChainClient("http://localhost:3011")
// Start SSE connection for automatic updates
ctx := context.Background()
tipChanges, err := client.Start(ctx)
if err != nil {
log.Fatal(err)
}
// Listen for tip changes (optional)
go func() {
for tip := range tipChanges {
log.Printf("New tip: height=%d hash=%s", tip.Height, tip.Hash)
}
}()
// Query methods (same interface as ChainManager)
tip := client.GetTip()
height := client.GetHeight()
header, err := client.GetHeaderByHeight(123456)
header, err := client.GetHeaderByHash(&hash)
// Cleanup
defer client.Stop()
```
Usage as a Server
```bash
# Build and run
go build -o server ./cmd/server
./server
# Configure via .env file
cp env.docker .env
# Edit .env with your settings
# Or configure via environment variables
CHAINTRACKS_PORT=3011 CHAINTRACKS_CHAINTRACKS_P2P_NETWORK=main ./server
```
Server starts on port 3011 with Swagger UI at `/docs`.
Docker Deployment
The easiest way to run go-chaintracks is with Docker:
```bash
# Quick start with default settings
docker compose up -d
# View logs
docker compose logs -f
```
This starts:
- **API Server** on port 3011 - REST API for header queries
- **CDN Server** on port 3012 - Static header files for bootstrap (optional)
Configure via environment variables in `.env`:
```bash
# Copy the example config
cp env.docker .env
# Key settings:
CHAIN=main # Network: main or test
CHAINTRACKS_MODE=embedded # Mode: embedded or remote
CDN_ENABLED=true # Enable CDN server on port 3012
BOOTSTRAP_URL=https://chaintracks-cdn-us-1.bsvb.tech # Bootstrap source
BOOTSTRAP_MODE=cdn # Bootstrap mode: cdn or api
```
API Endpoints
**API Server (port 3011):**
- `GET /v2/network` - Network name (main or test)
- `GET /v2/tip` - Chain tip header (JSON)
- `GET /v2/tip.bin` - Chain tip header (binary)
- `GET /v2/tip/stream` - SSE stream for real-time tip updates
- `GET /v2/header/height/:height` - Header by height (JSON)
- `GET /v2/header/height/:height.bin` - Header by height (binary)
- `GET /v2/header/hash/:hash` - Header by hash (JSON)
- `GET /v2/header/hash/:hash.bin` - Header by hash (binary)
- `GET /v2/headers?height=N&count=C` - Multiple headers (binary)
**CDN Server (port 3012, when enabled):**
- `GET /{network}NetBlockHeaders.json` - Metadata with file list
- `GET /{network}Net_{index}.headers` - Binary header files (100k headers each)
- `GET /health` - CDN health check
Full API documentation available at `/docs` when running.
Data Storage
Headers are stored in 100k-block files:
```text
~/.chaintracks/
├── mainNetBlockHeaders.json # Metadata
├── mainNet_0.headers # Blocks 0-99999
├── mainNet_1.headers # Blocks 100000-199999
└── ...
```
Each header is 80 bytes. Files use seek-based updates for efficient writes.
This format is compatible with the TypeScript chaintracks-server CDN format, allowing:
- Bootstrap from any CDN hosting these files
- Self-hosting your own CDN for other nodes to bootstrap from
Bootstrap Options
Two bootstrap modes are supported:
**CDN Mode (recommended):**
```bash
BOOTSTRAP_URL=https://chaintracks-cdn-us-1.bsvb.tech
BOOTSTRAP_MODE=cdn
```
Downloads headers from TypeScript CDN format files. Fast and efficient for initial sync.
**API Mode:**
```bash
BOOTSTRAP_URL=https://mainnet.gorillanode.io/api/v1
BOOTSTRAP_MODE=api
```
Fetches headers via REST API calls. Compatible with gorillanode-style endpoints.
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=master
```
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 run via [GitHub Actions](https://github.com/bsv-blockchain/go-chaintracks/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
```
## 🛠️ 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-chaintracks/stargazers)
## 📝 License
[](LICENSE)