https://github.com/bsv-blockchain/go-wallet-toolbox
Tools for building effective, compliant BRC-100 wallets in Go language.
https://github.com/bsv-blockchain/go-wallet-toolbox
bitcoin bitcoinsv brc100 bsv go wallet
Last synced: 4 months ago
JSON representation
Tools for building effective, compliant BRC-100 wallets in Go language.
- Host: GitHub
- URL: https://github.com/bsv-blockchain/go-wallet-toolbox
- Owner: bsv-blockchain
- License: other
- Created: 2025-03-17T07:47:45.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-24T09:20:20.000Z (4 months ago)
- Last Synced: 2026-03-24T16:36:47.119Z (4 months ago)
- Topics: bitcoin, bitcoinsv, brc100, bsv, go, wallet
- Language: Go
- Homepage:
- Size: 26.7 MB
- Stars: 9
- Watchers: 4
- Forks: 3
- Open Issues: 38
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
- Support: .github/SUPPORT.md
- Agents: .github/AGENTS.md
Awesome Lists containing this project
README
# 🧰 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](https://github.com/bsv-blockchain/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](https://golang.org/doc/devel/release.html#policy).
```shell script
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`):
```bash
go run ./cmd/infra_config_gen -k
```
2) Start the server:
```bash
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`.
## 📚 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](https://pkg.go.dev/github.com/bsv-blockchain/go-sdk)
- Monitor: `./docs/monitor.md`
- Storage Server: `./docs/storage_server.md`
- Storage: `./docs/storage.md`
- Wallet: `./docs/wallet.md`
### Examples & Usage Guides
Examples live under [`./examples`](/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](https://github.com/mrz1836/mage-x) build tool for development:
```shell script
go install github.com/mrz1836/mage-x/cmd/magex@latest
```
View all build commands
```bash script
magex help
```
Library Deployment
This project uses [goreleaser](https://github.com/goreleaser/goreleaser) for streamlined binary and library deployment to GitHub. To get started, install it via:
```bash
brew install goreleaser
```
The release process is defined in the [.goreleaser.yml](.goreleaser.yml) configuration file.
Then create and push a new Git tag using:
```bash
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](.github/AGENTS.md) before every commit:
```bash
go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
go-pre-commit install
```
The system is configured via [`.github/env/`](.github/env/README.md) and provides 17x faster execution than traditional Python-based pre-commit hooks. See the [complete documentation](http://github.com/mrz1836/go-pre-commit) for details.
GitHub Workflows
All workflows are driven by modular configuration in [`.github/env/`](.github/env/README.md) — no YAML editing required.
**[View all workflows and the control center →](.github/docs/workflows.md)**
Updating Dependencies
To update all dependencies (Go modules, linters, and related tools), run:
```bash
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](https://github.com/mrz1836/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](examples) run via [GitHub Actions](https://github.com/bsv-blockchain/go-wallet-toolbox/actions) and use [Go version 1.26.x](https://go.dev/doc/go1.26). View the [configuration file](.github/workflows/fortress.yml).
Run all tests (fast):
```bash script
magex test
```
Run all tests with race detector (slower):
```bash script
magex test:race
```
## ⚡ Benchmarks
Run the Go benchmarks:
```bash script
magex bench
```
## 🛠️ Code Standards
Read more about this Go project's [code standards](.github/CODE_STANDARDS.md).
## 🤖 AI Usage & Assistant Guidelines
Read the [AI Usage & Assistant Guidelines](.github/tech-conventions/ai-compliance.md) for details on how AI is used in this project and how to interact with AI assistants.
## 👥 Maintainers
| [
](https://github.com/icellan) | [
](https://github.com/galt-tr) | [
](https://github.com/mrz1836) |
|:--------------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------:|
| [Siggi](https://github.com/icellan) | [Dylan](https://github.com/galt-tr) | [MrZ](https://github.com/mrz1836) |
## 🤝 Contributing
View the [contributing guidelines](.github/CONTRIBUTING.md) and please follow the [code of conduct](.github/CODE_OF_CONDUCT.md).
### How can I help?
All kinds of contributions are welcome :raised_hands:!
The most basic way to show your support is to star :star2: the project, or to raise issues :speech_balloon:.
[](https://github.com/bsv-blockchain/go-wallet-toolbox/stargazers)
## 📝 License
[](LICENSE)