🛡  block-headers-service

Formerly known as "Pulse"

Go service for storing, indexing, and serving Bitcoin blockchain headers

CI / CD		Quality
Security		Community

Project Navigation

📦 About the Project	📦 Installation	📚 Documentation
🤝 Contributing	🛠️ Code Standards	⚡ Benchmarks
🤖 AI Usage	📝 License	👥 Maintainers

📘 About The Project

The Block Headers Service is a Go application that connects to the BSV P2P network to collect and serve information about blockchain headers—both historical and newly mined. It can run as a standalone application or as a module within a larger system.

The primary function is synchronizing with network peers to collect all block headers. On startup, the server initializes its components and connects to the BSV P2P network. Synchronization uses predefined checkpoints (specific known headers) to request headers in batches of 2,000 from peers. Each received header is stored in memory. Once fully synchronized, the server switches to listening mode, where it receives notifications from peers whenever a new block is mined.

For in-depth information and guidance, please refer to the SPV Wallet Documentation.

📦 Installation

block-headers-service requires a supported release of Go.

git clone https://github.com/bsv-blockchain/block-headers-service
go run ./cmd/main.go

📚 Documentation

API Reference

• Godoc – Dive into the API documentation at pkg.go.dev/github.com/bsv-blockchain/block-headers-service
• Swagger – Interactive API docs available at http://localhost:8080/swagger/index.html when running

Quick Start

Docker (recommended):

Pull image from Docker Hub:

docker pull bsvb/block-headers-service

Start a new instance:

docker run bsvb/block-headers-service:latest

From Source:

1. Install Go according to the installation instructions
2. Clone the repo and run:

git clone https://github.com/bsv-blockchain/block-headers-service
go run ./cmd/main.go

Docker Compose:

docker compose up --build

Package Install:

go get -u https://pkg.go.dev/github.com/bsv-blockchain/block-headers-service
go build -o block-headers-service
./block-headers-service

Authentication

Enabled by Default

The default assumes you want to use Authentication. This requires a single environment variable:

BHS_HTTP_AUTH_TOKEN=replace_me_with_token_you_want_to_use_as_admin_token

Disabling Auth Requirement

To disable authentication exposing all endpoints openly, set:

BHS_HTTP_USE_AUTH=false

Warning: We do not recommend exposing the server to the internet without authentication, as it would then be possible for anyone to prune your headers at will.

Authenticate with Admin Token

Add the following header to all requests:

Authorization: Bearer replace_me_with_token_you_want_to_use_as_admin_token

Additional Tokens

Create additional tokens:

POST https://{{block-headers-service_url}}/api/v1/access
Authorization: Bearer replace_me_with_token_you_want_to_use_as_admin_token

Response:

{
  "token": "some_token_created_by_server",
  "createdAt": "2023-05-11T10:20:16.227582Z",
  "isAdmin": false
}

Use the token in requests:

Authorization: Bearer some_token_created_by_server

Revoke a token:

DELETE https://{{block-headers-service_url}}/api/v1/access/{{some_token_created_by_server}}
Authorization: Bearer replace_me_with_token_you_want_to_use_as_admin_token

Configuration

Every variable which is used and can be configured is described in config.example.yaml

Defaults

If you run block headers service without editing anything, it will use the default configuration from defaults.go. It is set up to use sqlite database with enabled authorization (with default auth key) for the HTTP server.

Config Variables

Default config variables can be overridden by (in order of importance):

1. Flags (only the ones below)
2. ENV variables
3. Config file

Flags

  -C, --config_file string   custom config file path
  -h, --help                 show help
  -v, --version              show version
  -d, --dump_config          dump config to file, specified by config_file (-C) flag
  -e, --export_headers       export headers to file

Generate config file with defaults:

go run ./cmd/main.go -d

Use a custom config file:

go run ./cmd/main.go -C /my/config.yaml

Environment Variables

To override any config variable with ENV, use the BHS_ prefix with the path using _ as delimiter in uppercase.

Example from config.example.yaml:

websocket:
  history_max: 300
  history_ttl: 10

Override with:

BHS_WEBSOCKET_HISTORY_MAX=300

Connect to Testnet:

BHS_P2P_CHAIN_NET_TYPE=testnet

WebSocket Integration

Block headers service can notify clients via WebSockets when new headers are received.

Subscribing

Block headers service uses centrifugal/centrifuge to run a server. To integrate, choose a client library matching your programming language.

Go Example: See ./examples/ws-subscribe-to-new-headers/main.go for a complete example using centrifugal/centrifuge-go.

Webhooks

Creating a Webhook

POST https://{{block-headers-service_url}}/api/v1/webhook

Request body:

{
  "url": "<server_url>",
  "requiredAuth": {
    "type": "BEARER|CUSTOM_HEADER",
    "token": "<authorization_token>",
    "header": "<custom_header_name>"
  }
}

Auth Types:

• BEARER – Token placed in Authorization: Bearer {{token}} header
• CUSTOM_HEADER – Header built as {{header}}: {{token}}

Notes:

• URL must include http:// or https:// protocol
• If authorization is enabled, this request requires an Authorization header

Response:

{
  "url": "https://example.com/api/v1/webhook/new-header",
  "createdAt": "2023-05-11T13:05:23.297808+02:00",
  "lastEmitStatus": "",
  "lastEmitTimestamp": "0001-01-01T00:00:00Z",
  "errorsCount": 0,
  "active": true
}

Check Webhook

GET https://{{block-headers-service_url}}/api/v1/webhook?url={{webhook_url}}

Revoke Webhook

DELETE https://{{block-headers-service_url}}/api/v1/webhook?url={{webhook_url}}

Refresh Webhook

If the number of failed requests exceeds WEBHOOK_MAXTRIES, the webhook will be set to inactive. Use the create endpoint again to refresh it.

Database Management

Updating Predefined Database

When synchronization takes too long, it's recommended to export a fresh database with all headers using the -e flag:

go run ./cmd/main.go -e

Note: Export feature works only with SQLite database.

This creates a new .csv file with all headers in the same directory as the database file. Commit your changes and create a pull request with the new database file.

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

• Continuous Integration on Autopilot with GitHub Actions – every push is built, tested, and reported in minutes.
• Pull‑Request Flow That Merges Itself thanks to auto‑merge and hands‑free Dependabot auto‑merge.
• One‑Command Builds powered by battle‑tested MAGE-X targets for linting, testing, releases, and more.
• First‑Class Dependency Management using native Go Modules.
• Uniform Code Style via gofumpt plus zero‑noise linting with golangci‑lint.
• Confidence‑Boosting Tests with testify, the Go race detector, crystal‑clear HTML coverage snapshots, and automatic uploads to Codecov.
• Hands‑Free Releases delivered by GoReleaser whenever you create a new Tag.
• Relentless Dependency & Vulnerability Scans via Dependabot, Nancy and govulncheck.
• Security Posture by Default with CodeQL, OpenSSF Scorecard and secret‑leak detection via gitleaks.
• Automatic Syndication to pkg.go.dev on every release for instant godoc visibility.
• Polished Community Experience using rich templates for Issues & PRs.
• All the Right Meta Files (LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SUPPORT.md, SECURITY.md) pre‑filled and ready.
• Code Ownership clarified through a CODEOWNERS file, keeping reviews fast and focused.
• Zero‑Noise Dev Environments with tuned editor settings (.editorconfig) plus curated ignore files for VS Code, Docker, and Git.
• Label Sync Magic: your repo labels stay in lock‑step with .github/labels.yml.
• Friendly First PR Workflow – newcomers get a warm welcome thanks to a dedicated workflow.
• Standards‑Compliant Docs adhering to the standard‑readme spec.
• Instant Cloud Workspaces via Gitpod – spin up a fully configured dev environment with automatic linting and tests.
• Out‑of‑the‑Box VS Code Happiness with a preconfigured Go workspace and .vscode folder with all the right settings.
• Optional Release Broadcasts to your community via Slack, Discord, or Twitter – plug in your webhook.
• AI Playbook – machine‑readable guidelines in tech conventions.
• Go-Pre-commit System - High-performance Go-native pre-commit hooks with 17x faster execution—run the same formatting, linting, and tests before every commit, just like CI.
• Zero Python Dependencies - Pure Go implementation with environment-based configuration via .env.base.
• DevContainers for Instant Onboarding – Launch a ready-to-code environment in seconds with VS Code DevContainers and the included .devcontainer.json config.

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 .env.base and can be customized using also using .env.custom and provides 17x faster execution than traditional Python-based pre-commit hooks. See the complete documentation for details.

GitHub Workflows

🎛️ The Workflow Control Center

All GitHub Actions workflows in this repository are powered by a single configuration files – your one-stop shop for tweaking CI/CD behavior without touching a single YAML file! 🎯

Configuration Files:

• .env.base – Default configuration that works for most Go projects
• .env.custom – Optional project-specific overrides

This magical file controls everything from:

• ⚙️ Go version matrix (test on multiple versions or just one)
• 🏃 Runner selection (Ubuntu or macOS, your wallet decides)
• 🔬 Feature toggles (coverage, fuzzing, linting, race detection, benchmarks)
• 🛡️ Security tool versions (gitleaks, nancy, govulncheck)
• 🤖 Auto-merge behaviors (how aggressive should the bots be?)
• 🏷️ PR management rules (size labels, auto-assignment, welcome messages)

Workflow Name	Description
auto-merge-on-approval.yml	Automatically merges PRs after approval and all required checks, following strict rules.
codeql-analysis.yml	Analyzes code for security vulnerabilities using GitHub CodeQL.
dependabot-auto-merge.yml	Automatically merges Dependabot PRs that meet all requirements.
fortress.yml	Runs the GoFortress security and testing workflow, including linting, testing, releasing, and vulnerability checks.
pull-request-management.yml	Labels PRs by branch prefix, assigns a default user if none is assigned, and welcomes new contributors with a comment.
scorecard.yml	Runs OpenSSF Scorecard to assess supply chain security.
stale.yml	Warns about (and optionally closes) inactive issues and PRs on a schedule or manual trigger.
sync-labels.yml	Keeps GitHub labels in sync with the declarative manifest at .github/labels.yml.

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.24.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

🛠️ 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