🌿  go-subtree

A Go library for efficiently managing Bitcoin SV Subtree transaction structures.

CI / CD		Quality
Security		Community

Project Navigation

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

📖 Overview

go-subtree is a high-performance Go library for managing Bitcoin SV (BSV) merkle tree subtree structures. It provides efficient tools for organizing transactions hierarchically, essential for block assembly, transaction validation, and merkle proof generation in BSV blockchain infrastructure.

Core Capabilities

• Subtree Management: Create and manipulate merkle trees with dynamic node addition/removal
• Merkle Operations: Generate merkle proofs, calculate roots, handle incomplete trees
• Serialization: Binary format support for storage and transmission with streaming deserialization
• Transaction Tracking: Link full transaction data to tree nodes, track inpoints and conflicts
• Performance: Zero runtime dependencies, allocation-free operations, parallel tree computation

Target Use Cases

Bitcoin block construction, SPV proof generation, teranode transaction organization.

📦 Installation

go-subtree requires a supported release of Go.

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

📚 Documentation

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

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=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 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 environment 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

Benchmark Results

Benchmark Name	Iterations	ns/op	B/op	allocs/op
NewTxInpoints	4,245,616	300.7	644	3
Subtree_Deserialize	13	85,003,877	67,109,206	9
Subtree_DeserializeNodesFromReader	13	82,279,602	50,331,666	2
Subtree_DeserializeFromReader	14	82,479,347	67,108,952	7
SubtreeNodeIndex	2,659,832	440.5	45	1
Subtree_AddNode	135,712,501	11.85	0	0
Subtree_Serialize	36,528,111	46.54	155	0
Subtree_SerializeNodes	100,000,000	10.94	32	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 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	Simon	Stu	Liam	Gokhan	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