🚀 go-wire

BSV Blockchain Wire Protocol

CI / CD	Quality & Security	Docs & Meta	Community

🗂️ Table of Contents

• What's Inside
• Installation
• Documentation
• Examples & Tests
• Benchmarks
• Code Standards
• AI Compliance
• Maintainers
• Contributing
• License

🧩 What's Inside

Package wire implements the bitcoin wire protocol. A comprehensive suite of tests with 100% test coverage is provided to ensure proper functionality.

This package has intentionally been designed so it can be used as a standalone package for any projects needing to interface with bitcoin peers at the wire protocol level.

📦 Installation

go-wire requires a supported release of Go.

go get -u github.com/bsv-blockchain/go-wire

📚 Documentation

• API Reference – Dive into the godocs at pkg.go.dev/github.com/bsv-blockchain/go-wire
• Usage Examples – Browse practical patterns either the examples directory or view the example functions
• Benchmarks – Check the latest numbers in the benchmark results
• Test Suite – Review both the unit tests and fuzz tests (powered by testify)

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 Make 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 Compliance Playbook – machine‑readable guidelines (AGENTS.md, CLAUDE.md, .cursorrules, sweep.yaml) keep ChatGPT, Claude, Cursor & Sweep aligned with your repo’s rules.
• Pre-commit Hooks for Consistency powered by pre-commit and the .pre-commit-config.yaml file—run the same formatting, linting, and tests before every commit, just like CI.
• Automated Hook Updates keep the .pre-commit-config.yaml current via a weekly workflow.
• 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.

To generate a snapshot (non-versioned) release for testing purposes, run:

make release-snap

Then create and push a new Git tag using:

make tag version=x.y.z

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

Makefile Commands

View all makefile commands

make help

List of all current commands:

bench                 ## Run all benchmarks in the Go application
build-go              ## Build the Go application (locally)
citation              ## Update version in CITATION.cff (use version=X.Y.Z)
clean-mods            ## Remove all the Go mod cache
coverage              ## Show test coverage
diff                  ## Show git diff and fail if uncommitted changes exist
fumpt                 ## Run fumpt to format Go code
generate              ## Run go generate in the base of the repo
godocs                ## Trigger GoDocs tag sync
govulncheck-install   ## Install govulncheck (pass VERSION= to override)
govulncheck           ## Scan for vulnerabilities
help                  ## Display this help message
install-go            ## Install using go install with specific version
install-releaser      ## Install GoReleaser
install-stdlib        ## Install the Go standard library for the host platform
install-template      ## Kick-start a fresh copy of go-template (run once!)
install               ## Install the application binary
lint-version          ## Show the golangci-lint version
lint                  ## Run the golangci-lint application (install if not found)
loc                   ## Total lines of code table
mod-download          ## Download Go module dependencies
mod-tidy              ## Clean up go.mod and go.sum
pre-build             ## Pre-build all packages to warm cache
release-snap          ## Build snapshot binaries
release-test          ## Run release dry-run (no publish)
release               ## Run production release (requires github_token)
tag-remove            ## Remove local and remote tag (use version=X.Y.Z)
tag-update            ## Force-update tag to current commit (use version=X.Y.Z)
tag                   ## Create and push a new tag (use version=X.Y.Z)
test-ci-no-race       ## CI test suite without race detector
test-ci               ## CI test runs tests with race detection and coverage (no lint - handled separately)
test-cover-race       ## Runs unit tests with race detector and outputs coverage
test-cover            ## Unit tests with coverage (no race)
test-fuzz             ## Run fuzz tests only (no unit tests)
test-no-lint          ## Run only tests (no lint)
test-parallel         ## Run tests in parallel (faster for large repos)
test-race             ## Unit tests with race detector (no coverage)
test-short            ## Run tests excluding integration tests (no lint)
test                  ## Default testing uses lint + unit tests (fast)
uninstall             ## Uninstall the Go binary
update-linter         ## Upgrade golangci-lint (macOS only)
update-releaser       ## Reinstall GoReleaser
update                ## Update dependencies
vet-parallel          ## Run go vet in parallel (faster for large repos)
vet                   ## Run go vet only on your module packages

GitHub Workflows

🎛️ The Workflow Control Center

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

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)
• 🛡️ Security tool versions (gitleaks, nancy, govulncheck)
• 🤖 Auto-merge behaviors (how aggressive should the bots be?)
• 🏷️ PR management rules (size labels, auto-assignment, welcome messages)

Pro tip: Want to disable code coverage? Just flip ENABLE_CODE_COVERAGE=false in .env.shared and push. No YAML archaeology required!

Workflow Name	Description
auto-merge-on-approval.yml	Automatically merges PRs after approval and all required checks, following strict rules.
codeql.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.
update-python-dependencies.yml	Updates Python dependencies for pre-commit hooks in the repository.
update-pre-commit-hooks.yml	Automatically update versions for pre-commit hooks

Updating Dependencies

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

make update

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

Pre-commit Hooks

Set up the optional pre-commit hooks to run the same formatting, linting, and tests defined in AGENTS.md before every commit:

pip install pre-commit
pre-commit install

The hooks are configured in .pre-commit-config.yaml and mirror the CI pipeline.

🧪 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):

make test

Run all tests with race detector (slower):

make test-race

⚡ Benchmarks

Run the Go benchmarks:

make bench

Benchmark Results

Benchmark	Iterations	ns/op	B/op	allocs/op
WriteVarInt1	39,459,027	29.66	0	0
WriteVarInt3	20,199,483	58.82	0	0
WriteVarInt5	19,839,806	60.09	0	0
WriteVarInt9	20,289,205	58.85	0	0
ReadVarInt1	34,616,506	34.46	0	0
ReadVarInt3	16,991,710	70.22	0	0
ReadVarInt5	17,296,663	69.03	0	0
ReadVarInt9	17,292,540	68.81	0	0
ReadVarStr4	19,168,129	61.24	8	2
ReadVarStr10	17,873,167	66.25	32	2
WriteVarStr4	26,292,486	44.63	8	1
WriteVarStr10	24,418,180	48.74	16	1
ReadOutPoint	28,408,053	41.95	0	0
WriteOutPoint	37,229,792	31.65	0	0
ReadTxOut	11,092,542	108.00	0	0
WriteTxOut	19,576,215	61.21	0	0
ReadTxIn	8,187,141	148.00	0	0
WriteTxIn	12,787,064	93.58	0	0
DeserializeTxSmall	2,368,681	510.50	208	5
SerializeTx	4,343,654	277.00	0	0
ReadBlockHeader	7,429,682	160.40	0	0
WriteBlockHeader	7,074,567	169.20	12	3
DecodeGetHeaders	198,742	5896.00	20480	2
DecodeHeaders	2,761	431936.00	229380	2
DecodeGetBlocks	197,142	5944.00	20480	2
DecodeAddr	8,107	144051.00	89730	1002
DecodeInv	464	2573857.00	2203667	2
DecodeNotFound	463	2583316.00	2203666	2
DecodeMerkleBlock	736,904	1598.00	4368	3
TxHash	2,120,943	566.40	256	2
DoubleHashB	6,433,498	186.70	32	1
DoubleHash	6,658,620	182.00	0	0

These benchmarks reflect fast, allocation-free lookups for most retrieval functions, ensuring optimal performance in production environments. Performance benchmarks for the core functions in this library, executed on an Apple M1 Max (ARM64).

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Compliance

This project documents expectations for AI assistants using a few dedicated files:

• AGENTS.md — canonical rules for coding style, workflows, and pull requests used by Codex.
• CLAUDE.md — quick checklist for the Claude agent.
• .cursorrules — machine-readable subset of the policies for Cursor and similar tools.
• sweep.yaml — rules for Sweep, a tool for code review and pull request management.

Edit AGENTS.md first when adjusting these policies, and keep the other files in sync within the same pull request.

👥 Maintainers

Siggi

🤝 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 💬. You can also support this project by becoming a sponsor on GitHub 👏 to ensure this journey continues indefinitely! 🚀

📝 License