spv-wallet

KO | EN

gitlite — search

#python #docker #flutter #github-actions #covid-19 #flask #rust #java #javascript #database #coronavirus #php

★ 69 Open GitHub ↗

Open-source non-custodial hosted wallet for the BSV Blockchain (UTXOs, xPubs, Paymail & More!)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🧰&nbsp;&nbsp;spv-wallet

**Comprehensive Go noncustodial wallet for the BSV blockchain**

<table align="center" border="0">
 <tr>
 <td align="right">
 <code>CI / CD</code> &nbsp;&nbsp;
 </td>
 <td align="left">
 <a href="https://github.com/bsv-blockchain/spv-wallet/actions"><img src="https://img.shields.io/github/actions/workflow/status/bsv-blockchain/spv-wallet/fortress.yml?branch=main&label=build&logo=github&style=flat-square" alt="Build"></a>
 <a href="https://github.com/bsv-blockchain/spv-wallet/actions"><img src="https://img.shields.io/github/last-commit/bsv-blockchain/spv-wallet?style=flat-square&logo=git&logoColor=white&label=last%20update" alt="Last Commit"></a>
 </td>
 <td align="right">
 &nbsp;&nbsp;&nbsp;&nbsp; <code>Quality</code> &nbsp;&nbsp;
 </td>
 <td align="left">
 <a href="https://codecov.io/gh/bsv-blockchain/spv-wallet"><img src="https://codecov.io/gh/bsv-blockchain/spv-wallet/branch/main/graph/badge.svg?style=flat-square" alt="Coverage"></a>
 </td>
 </tr>

<tr>
 <td align="right">
 <code>Security</code> &nbsp;&nbsp;
 </td>
 <td align="left">
 <a href="https://scorecard.dev/viewer/?uri=github.com/bsv-blockchain/spv-wallet"><img src="https://api.scorecard.dev/projects/github.com/bsv-blockchain/spv-wallet/badge?style=flat-square" alt="Scorecard"></a>
 <a href=".github/SECURITY.md"><img src="https://img.shields.io/badge/policy-active-success?style=flat-square&logo=security&logoColor=white" alt="Security"></a>
 </td>
 <td align="right">
 &nbsp;&nbsp;&nbsp;&nbsp; <code>Community</code> &nbsp;&nbsp;
 </td>
 <td align="left">
 <a href="https://github.com/bsv-blockchain/spv-wallet/graphs/contributors"><img src="https://img.shields.io/github/contributors/bsv-blockchain/spv-wallet?style=flat-square&color=orange" alt="Contributors"></a>
 <a href="https://deepwiki.com/bsv-blockchain/spv-wallet"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
 </td>
 </tr>
</table>

</div>

### <code>Project Navigation</code>

</div>

<table align="center">
 <tr>
 <td align="center" width="33%">
 📦&nbsp;<a href="#-installation"><code>Installation</code></a>
 </td>
 <td align="center" width="33%">
 🧪&nbsp;<a href="#-examples--tests"><code>Examples&nbsp;&&nbsp;Tests</code></a>
 </td>
 <td align="center" width="33%">
 📚&nbsp;<a href="#-documentation"><code>Documentation</code></a>
 </td>
 </tr>
 <tr>
 <td align="center">
 🤝&nbsp;<a href="#-contributing"><code>Contributing</code></a>
 </td>
 <td align="center">
 🛠️&nbsp;<a href="#-code-standards"><code>Code&nbsp;Standards</code></a>
 </td>
 <td align="center">
 ⚡&nbsp;<a href="#-benchmarks"><code>Benchmarks</code></a>
 </td>
 </tr>
 <tr>
 <td align="center">
 🤖&nbsp;<a href="#-ai-usage--assistant-guidelines"><code>AI&nbsp;Usage</code></a>
 </td>
 <td align="center">
 📝&nbsp;<a href="#-license"><code>License</code></a>
 </td>
 <td align="center">
 👥&nbsp;<a href="#-maintainers"><code>Maintainers</code></a>
 </td>
 </tr>
</table>

## 📦 Installation

**spv-wallet-go-client** requires a [supported release of Go](https://golang.org/doc/devel/release.html#policy).
```shell script
go get -u github.com/bsv-blockchain/spv-wallet
```

Build the binary:
```shell script
go build -o spv-wallet cmd/*
```

Run the binary:
```shell script
./spv-wallet
```

## 📚 Documentation

- **API Reference** – Dive into the godocs at [pkg.go.dev/github.com/bsv-blockchain/spv-wallet](https://pkg.go.dev/github.com/bsv-blockchain/spv-wallet)
- **Test Suite** – Review both the unit tests and fuzz tests (powered by [`testify`](https://github.com/stretchr/testify))
- **SPV Wallet Docs** - please refer to the [SPV Wallet Documentation](https://docs.bsvblockchain.org/network-topology/spv-wallet)

<details>
<summary><code>Development Build Commands</code></summary>

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

</details>

<details>
<summary><code>Makefile Commands</code></summary>

View all `makefile` commands

```shell script
make help
```

List of all current commands:

```text
all                           Runs multiple commands
clean                         Remove previous builds and any cached data
clean-mods                    Remove all the Go mod cache
coverage                      Shows the test coverage
diff                          Show the git diff
generate                      Runs the go generate command in the base of the repo
godocs                        Sync the latest tag with GoDocs
help                          Show this help message
install                       Install the application
install-go                    Install the application (Using Native Go)
install-releaser              Install the GoReleaser application
lint                          Run the golangci-lint application (install if not found)
release                       Full production release (creates release in GitHub)
release                       Runs common.release then runs godocs
release-snap                  Test the full release (build binaries)
release-test                  Full production test release (everything except deploy)
replace-version               Replaces the version in HTML/JS (pre-deploy)
tag                           Generate a new tag and push (tag version=0.0.0)
tag-remove                    Remove a tag if found (tag-remove version=0.0.0)
tag-update                    Update an existing tag to current commit (tag-update version=0.0.0)
test                          Runs lint and ALL tests
test-ci                       Runs all tests via CI (exports coverage)
test-ci-no-race               Runs all tests via CI (no race) (exports coverage)
test-ci-short                 Runs unit tests via CI (exports coverage)
test-no-lint                  Runs just tests
test-short                    Runs vet, lint and tests (excludes integration tests)
test-unit                     Runs tests and outputs coverage
uninstall                     Uninstall the application (and remove files)
update-linter                 Update the golangci-lint package (macOS only)
vet                           Run the Go vet application
```

</details>

<details>
<summary>Repository Features</summary>

This repository includes 25+ built-in features covering CI/CD, security, code quality, developer experience, and community tooling.

**[View the full Repository Features list →](.github/docs/repository-features.md)**

</details>

<details>
<summary><code>Library Deployment</code></summary>

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.

</details>

<details>
<summary><code>Pre-commit Hooks</code></summary>

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 modular env files in [`.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.

</details>

<details>
<summary>GitHub Workflows</summary>

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

</details>

<details>
<summary><code>Updating Dependencies</code></summary>

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.

</details>

<details>
<summary><code>Usage & Configuration</code></summary>

Every configurable variable is described in [config.example.yaml](config.example.yaml).

**Default Configuration:**

Running `spv-wallet` without configuration uses defaults from [defaults.go](/config/defaults.go):
- Cache: freecache
- Database: SQLite
- Paymail: enabled (signing disabled)
- BEEF: enabled

</details>

<details>
<summary><code>Config Variables</code></summary>

Default config variables can be overridden by (in order of priority):
1. **Flags** (highest priority)
2. **Environment variables**
3. **Config file** (lowest priority)

### Flags

```bash
-C, --config_file string   custom config file path
-h, --help                 show help
-v, --version              show version
-d, --dump_config          dump config to file, specified by config_file (-C) flag
```

**Generate config file with defaults:**

```bash
go run ./cmd/main.go -d
```

The default config file path is the **project root** with filename **config.yaml**. Override with the `-C` flag:

```bash
go run ./cmd/main.go -C /my/config.json
```

### Environment Variables

Override any config variable using the `SPVWALLET_` prefix with the mapstructure annotation path (use `_` as delimiter, all uppercase).

**Example:** Given this fragment from `config.example.yaml`:

```yaml
auth:
    admin_key: xpub...
    require_signing: false
    scheme: xpub
```

Override `admin_key` with:

```bash
SPVWALLET_AUTH_ADMIN_KEY="your_admin_key"
```

### TAAL API Key

To use TAAL services, an API key is required.

**Getting an API Key:**
1. Visit [platform.taal.com](https://platform.taal.com/)
2. Register or login to TAAL Platform
3. Find your mainnet and testnet API keys on the dashboard

See the [TAAL documentation](https://docs.taal.com/introduction/get-an-api-key) for details.

**Configuration:** Add your key to `config.example.yaml` at `nodes` → `apis` → `token`

</details>

<details>
<summary><code>Docker Compose Quickstart</code></summary>

The `start.sh` script uses `docker-compose.yml` to start SPV Wallet with web-frontend, web-backend, and your choice of database and cache storage.

### Running Options

**Manual Configuration** (interactive prompts):

```bash
./start.sh
```

**Flag-based Configuration:**

```bash
./start.sh -db postgresql -c redis -sw true -b false
```

Run `./start.sh -h` or `./start.sh --help` to see all available options.

**Load Previous Configuration:**

```bash
./start.sh -l
```

This uses a previously created `.env.config` file.

### Service Ports

| Port | Service                   |
|------|---------------------------|
| 3002 | SPV Wallet web-frontend   |
| 8180 | SPV Wallet web-backend    |
| 3003 | SPV Wallet (core service) |
| 3000 | SPV Wallet admin          |
| 5432 | PostgreSQL DB             |
| 6379 | Redis                     |
| 8080 | Block Headers Service     |
| 80   | Paymail domain (HTTP)     |
| 443  | Paymail domain (HTTPS)    |

</details>

## 🧪 Examples & Tests

All unit tests and [examples](examples) run via [GitHub Actions](https://github.com/bsv-blockchain/spv-wallet/actions) and use [Go version 1.25.x](https://go.dev/doc/go1.25). 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
| [<img src="https://github.com/icellan.png" height="50" alt="Siggi" />](https://github.com/icellan) | [<img src="https://github.com/galt-tr.png" height="50" alt="Galt" />](https://github.com/galt-tr) | [<img src="https://github.com/mrz1836.png" height="50" alt="MrZ" />](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:.

[![Stars](https://img.shields.io/github/stars/bsv-blockchain/spv-wallet?label=Please%20like%20us&style=social&v=1)](https://github.com/bsv-blockchain/spv-wallet/stargazers)

## 📝 License

[![License](https://img.shields.io/badge/license-OpenBSV-blue?style=flat&logo=springsecurity&logoColor=white)](https://raw.githubusercontent.com/bsv-blockchain/spv-wallet/main/LICENSE)

spv-wallet

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README