📣 Notice: Discussion underway about consolidating this repository into the go-stack monorepo. No archive decision has been made yet — please weigh in at bsv-blockchain/roadmap discussion #70 before any change is made.

🧰  go-wallet-toolbox

BSV wallet toolbox for blockchain interactions and wallet management.

CI / CD		Quality
Security		Community

Project Navigation

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

📖 About

Welcome to the BSV Blockchain Wallet Toolbox for Go — a BRC-100 conforming collection of wallet components that provide storage, services, and a minimal storage server, all built on top of the official Go SDK. This toolbox gives you everything you need to assemble scalable, production-ready wallet-backed applications and services.

The toolbox provides interlocking, production-ready building blocks for BSV wallet applications: persistent storage, protocol-based key derivation, wallet orchestration, and seamless integrations with blockchain services. By complementing the lower-level primitives in the Go SDK, it enables SPV-friendly, privacy-preserving, and scalable wallet workflows.

Features

• Protocol-aligned wallet flows (BRC-100 concepts).
• Persistent, queryable wallet state (SQLite/MySQL/Postgres via GORM).
• Pluggable service layer (ARC, WOC, Bitails, BHS) with configurable credentials.
• Background tasks for SPV-friendly workflows and reliable broadcasting.
• Example-driven guidance for common wallet actions and service integrations.

📦 Installation

go-wallet-toolbox requires a supported release of Go.

go get -u github.com/bsv-blockchain/go-wallet-toolbox

Quick Start: Storage Server

Run a local storage server for development/testing.

1. Generate a config (or copy infra-config.example.yaml):

go run ./cmd/infra_config_gen -k

2. Start the server:

go run ./cmd/infra

Defaults:

• HTTP listens on port 8100 (see infra-config.example.yaml)
• SQLite at ./storage.sqlite by default

For a guided walkthrough (including faucet and local setup), see the examples overview below and the server notes in examples/README.md.

Networks

Set bsv_network in the config (or BSV_NETWORK / <PREFIX>_BSV_NETWORK in the env) to one of:

bsv_network	Description	Broadcast / merkle proofs	Headers	WhatsOnChain
main	Public mainnet	ARC (TAAL) + Arcade + GorillaPool failover	WhatsOnChain	✅
test	Public testnet	ARC (TAAL testnet)	WhatsOnChain	✅
ttn	Teranode Test Net (public scaling testnet)	Arcade (arcade-v2-ttn-us-1.bsvblockchain.tech)	ChainTracks (…/chaintracks)	✅
tstn	Teranode Scaling Test Net (private, per-deployment)	Arcade ($TSTN_ARCADE_URL)	ChainTracks ($TSTN_CHAINTRACKS_URL)	❌ (not available)

ttn and tstn are testnet-based (testnet address/key encoding and overlay network).

tstn is private — its endpoints are not public and must be supplied at runtime via environment variables:

Variable	Required	Meaning
TSTN_ARCADE_URL	Yes	Arcade broadcaster / ARC endpoint base. Also the ChainTracks fallback host.
TSTN_CHAINTRACKS_URL	No	ChainTracks base URL (client appends /v2/...). Defaults to ${TSTN_ARCADE_URL}/chaintracks when omitted.

Selecting tstn without at least TSTN_ARCADE_URL fails startup with an actionable error.

📚 Documentation

• Core concepts and examples: ./examples/README.md
• Complex example: ./examples/complex_wallet_examples/create_faucet_server/QUICK_START.md
• Config template: ./infra-config.example.yaml
• Underlying primitives: Go SDK docs
• Monitor: ./docs/monitor.md
• Storage Server: ./docs/storage_server.md
• Storage: ./docs/storage.md
• Wallet: ./docs/wallet.md
• Throughput Docker live-test (privacy vs 1000 TPS stack): ./docs/throughput-docker.md
• Throughput demo dashboard (mainnet compose, fund → FuelKeeper → stream runbook): ./docs/throughput-dashboard.md

Examples & Usage Guides

Examples live under ./examples and are grouped by purpose:

• wallet_examples/: end-to-end wallet actions (create P2PKH/data tx, balance, encryption, internalize, batching).
• services_examples/: interactions with external services (headers, BEEF, status checks, WOC/ARC helpers, etc.).
• complex_wallet_examples/create_faucet_server/: a runnable faucet server with Docker support.

Start with examples/README.md for a step‑by‑step flow (fund via faucet → check balance → create/send transactions). Quick start for the faucet server is in examples/complex_wallet_examples/create_faucet_server/QUICK_START.md.

Building Blocks

• Wallet (pkg/wallet): high-level wallet orchestration over SDK primitives and templates.
• Storage (pkg/storage): durable records for actions, outputs, users, tx notes, and related entities.
• Storage Server (cmd/infra, pkg/infra): minimal HTTP server to persist wallet actions and coordinate background tasks.
• Wallet Services (pkg/services): integrations for transaction broadcast, headers, proofs, exchange rates, and related service APIs.

Complementary modules you may use:

• Monitor (pkg/monitor): background tasks (send waiting, fail abandoned, sync statuses, etc.).
• WDK/Assembler (pkg/wdk, pkg/internal/assembler): transaction assembly helpers.

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

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