⛓️  BSV Blockchain | Go SDK

A unified, peer-to-peer, SPV-first Software Development Kit for building scalable applications on the BSV Blockchain in Go.

CI / CD		Quality
Security		Community

Project Navigation

📦 Installation	🚀 Basic Usage	✨ Features	🧪 Examples
📚 Documentation	🧰 Tests	🛠️ Code Standards	🤖 AI Usage
🤝 Contributing	👥 Maintainers	⚖️ License	🔗 Go Docs

🧩 What's Inside

The BSV Blockchain Go SDK provides an updated and unified layer for developing scalable applications on the BSV Blockchain. This SDK addresses the limitations of previous tools by offering a fresh, peer-to-peer approach, adhering to SPV, and ensuring privacy and scalability.

It is a comprehensive toolkit for the full transaction lifecycle — constructing, signing, verifying, and broadcasting transactions — alongside cryptographic primitives, a network-compliant script interpreter, a BRC-100 wallet framework, peer authentication, overlay networks, identity, and on-chain storage.

📦 Installation

go-sdk requires a supported release of Go.

go get github.com/bsv-blockchain/go-sdk

🚀 Basic Usage

Here's a simple example of using the SDK to create and sign a P2PKH transaction:

package main

import (
    "log"

    ec "github.com/bsv-blockchain/go-sdk/primitives/ec"
    "github.com/bsv-blockchain/go-sdk/transaction"
    "github.com/bsv-blockchain/go-sdk/transaction/template/p2pkh"
)

func main() {
    // 1) Load a private key (WIF shown for example purposes)
    priv, _ := ec.PrivateKeyFromWif("KznvCNc6Yf4iztSThoMH6oHWzH9EgjfodKxmeuUGPq5DEX5maspS")

    // 2) Create a new transaction
    tx := transaction.NewTransaction()

    // 3) Build an unlocker for P2PKH
    unlocker, _ := p2pkh.Unlock(priv, nil)

    // 4) Add an input with its source output details
    //    If you don't have the source tx, fetch satoshis+lockingScript for the outpoint
    _ = tx.AddInputFrom(
        "11b476ad8e0a48fcd40807a111a050af51114877e09283bfa7f3505081a1819d", // prev txid
        0,                                                                  // vout
        "76a9144bca0c466925b875875a8e1355698bdcc0b2d45d88ac",              // source locking script
        1500,                                                               // source satoshis
        unlocker,                                                           // unlocking script template
    )

    // 5) Add an output
    _ = tx.PayToAddress("1AdZmoAQUw4XCsCihukoHMvNWXcsd8jDN6", 1000)

    // 6) Sign all inputs with attached templates
    if err := tx.Sign(); err != nil {
        log.Fatal(err)
    }
    log.Printf("tx hex: %s\n", tx.Hex())
}

See the Go Doc for a complete list of available modules and functions.

✨ Features

• Transaction Construction & Signing — a comprehensive, versatile transaction builder for secure creation, signing, and serialization.
• BEEF & Atomic BEEF — first-class support for the BEEF (Background Evaluation Extended Format) and Atomic BEEF transaction formats.
• Script & Interpreter — Bitcoin script types, BIP-276 serialization, and a full, network-compliant script interpreter.
• Script Templates — reusable locking/unlocking templates including p2pkh and pushdrop.
• Fees, Broadcasters & Chain Trackers — sats/kb fee modeling plus ready-made broadcasters (ARC, TAAL, WhatsOnChain) and chain trackers.
• Cryptographic Primitives — EC keys, ECDSA, Schnorr, hashing, AES (CBC/GCM), and DRBG for secure key management and signatures.
• Type-42 Key Derivation — private/public key derivation for shared, invoice-numbered key universes.
• Shamir Key Splitting — split a private key into N shares and recombine from any M of N.
• SPV & Merkle Proofs — serializable SPV structures and tools for representing and verifying merkle proofs.
• Secure Messaging (BRC-77) — sign, verify, and encrypt recipient-specific messages.
• Wallet Framework — a complete BRC-100 wallet Interface, ProtoWallet, wire-protocol serializer, and HTTP substrate.
• Peer Authentication (BRC-103/104) — mutual auth with master/verifiable certificates over HTTP and WebSocket transports.
• Overlay Networks — SHIP/SLAP topic broadcast and lookup/discovery for overlay services.
• Identity, Registry & KV Store — identity resolution, on-chain protocol/basket/certificate definitions, and on-chain key-value storage.
• File Storage (UHRP) — upload and download content addressed by UHRP URLs.
• Compatibility Packages — Base58, BIP32 (HD keys), BIP39 (mnemonics), Bitcoin Signed Message (BSM), and ECIES.

🧪 Examples

Every example below is self-contained and thoroughly commented. Browse the full set in the examples directory.

Transactions

• Broadcaster — Broadcast a transaction to the network (ARC/GorillaPool & WhatsOnChain).
• Create Simple TX — Build and sign a basic P2PKH transaction.
• Create TX With Inscription — Create a transaction with an Ordinal inscription.
• Create TX With OP_RETURN — Embed data in a transaction with an OP_RETURN output.
• Fee Modeling — Calculate and model transaction fees.
• Set Source TX Output — Provide UTXO data (satoshis + locking script) to enable signing.
• Validate SPV — Validate SPV by decoding BEEF and checking merkle roots.
• Verify BEEF — Verify a BEEF structure.
• Verify Transaction — Verify a transaction's scripts, merkle path, and fees.
• GoBDK Integration — Opt into native transaction validation and secp256k1 signatures.

Keys & Addresses

• Address From WIF — Derive an address from a WIF private key.
• Derive Child Key — Derive a child key using the BRC-42 method.
• Generate HD Key — Generate a new hierarchical deterministic (HD) key.
• HD Key From XPub — Create an HD key from an extended public key (xPub).
• Key Shares To Backup — Split a private key into Shamir key-share backups.
• Key Shares From Backup — Reconstruct a private key from key shares.

Messaging & Authentication

• Authenticated Messaging — Authenticated peer messaging over a transport.
• ECIES Single — ECIES encryption/decryption for a single recipient.
• ECIES Shared — ECIES using a shared secret between two parties.
• ECIES Electrum Binary — Electrum-compatible ECIES (binary format).
• Encrypted Message — Encrypt/decrypt and sign/verify messages.
• Identity Client — Create an identity client and reveal certificate attributes.

Wallet

• Create Wallet — Generate entropy/mnemonic and create a new wallet.
• Get Public Key — Retrieve an identity public key from a wallet.
• Create Signature — Create a digital signature with a wallet.
• Create HMAC — Create and verify an HMAC via a wallet.
• Encrypt Data — Encrypt/decrypt data between wallets.
• HTTP Wallet — Interact with a wallet using JSON over HTTP.

Registry

• Registry Register — Register a basket definition with the registry.
• Registry Resolve — Resolve a basket definition from the registry.

Storage

• Storage Uploader — Upload content to a storage service using a wallet.
• Storage Downloader — Download a file via a UHRP URL.

Networking

• WebSocket Peer — Peer communication over WebSocket.

Cryptography

• AES — Symmetric AES encryption/decryption examples.

Migration Guides

• Converting from go-bt — Guide for migrating from go-bt.

📚 Documentation

This SDK is supported by multiple layers of documentation:

• API Reference — the complete godocs at pkg.go.dev/github.com/bsv-blockchain/go-sdk.
• Examples — common usage patterns in the examples directory.
• Concepts — high-level concepts and architectural decisions in docs/concepts.
• Low-Level Details — implementation details and specifications in docs/low-level.
• Script Interpreter — deep-dive documentation of the Bitcoin script interpreter, based on the Bitcoin Script specification.

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 ships with a large set of built-in features covering CI/CD, security, code quality, developer experience, and community tooling.

View the full Repository Features list →

GitHub Workflows

All workflows are driven by modular configuration in .github/env/ — no YAML editing required.

View all workflows and the control center →

Pre-commit Hooks

Set up the Go-Pre-commit System to run the same formatting, linting, and tests 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 and provides much faster execution than traditional Python-based pre-commit hooks. See the complete documentation for details.

Library Deployment

This project uses goreleaser for streamlined library deployment to GitHub. Install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file. Create and push a new Git tag using:

magex version:bump push=true bump=patch branch=master

This ensures consistent, repeatable releases with properly versioned artifacts.

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This brings all dependencies up to date in a single step, keeping your development environment and CI in sync with the latest versions.

🧰 Tests

All unit tests run via GitHub Actions using the GoFortress workflow suite.

Run all tests (fast):

magex test

Run all tests with the race detector (slower):

magex test:race

🛠️ 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	Darren	Luke	MrZ

🤝 Contributing

We're always looking for contributors to help us improve the SDK. Whether it's bug reports, feature requests, or pull requests — all contributions are welcome.

1. Fork & Clone — fork this repository and clone it to your local machine.
2. Set Up — run go get github.com/bsv-blockchain/go-sdk to get all the modules.
3. Make Changes — create a new branch and make your changes.
4. Test — ensure all tests pass by running magex test (or go test ./...).
5. Commit — commit your changes and push to your fork.
6. Pull Request — open a pull request from your fork to this repository.

View the contributing guidelines and please follow the code of conduct. For information on past releases, check out the changelog.

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

The license for the code in this repository is the Open BSV License. Refer to LICENSE for the license text.