🔁  go-tx-map

High-performance, concurrent-safe Go data structures for transaction hash and key-value mapping.

CI / CD		Quality
Security		Community

Project Navigation

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

📦 Installation

go-tx-map requires a supported release of Go.

go get -u github.com/bsv-blockchain/go-tx-map

📚 Documentation

• API Reference – Dive into the godocs at pkg.go.dev/github.com/bsv-blockchain/go-tx-map
• 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)

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 env 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

Choosing an Implementation

The library offers two backend implementations for each map type:

Implementation	Use when
Native (default)	Speed matters — general-purpose use, delete-heavy workloads, latency-sensitive code. Use NewDefaultMap, NewDefaultMapUint64, NewDefaultSplitMap, etc., or the explicit NewNative* constructors.
Dolthub	Memory matters — large maps (100M+ entries), RAM-constrained environments. Use NewSwissMap, NewSwissMapUint64, NewSplitSwissMap, etc.

• Native uses Go's built-in map (Swiss Tables in Go 1.24+). It is typically 5–46% faster for most operations.
• Dolthub uses dolthub/swiss and uses ~27–30% less memory at 100M entries.

Benchmark Results

Benchmark	Iterations	ns/op	B/op	allocs/op
Bytes2Uint16Buckets	1,000,000,000	0.31	0	0
ConvertSyncMapToUint32Slice	123,170	9,704	12,920	11
ConvertSyncedMapToUint32Slice	94,824	12,860	12,920	11
NewSplitSwissLockFreeMapUint64	7,581	141,465	302,791	4,112
NewSplitSwissMap	6,442	169,322	504,418	4,107
NewSplitSwissMapUint64	5,205	192,413	532,395	4,112
NewSwissLockFreeMapUint64	624,360	1,776	19,664	3
NewSwissMap	367,938	3,101	42,192	3
NewSwissMapUint64	309,972	3,521	50,384	3

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