BSV blockchainBSV blockchain

Use the Go SDK

Use go-sdk to build keys, scripts, transactions and proofs for the BSV blockchain in Go, from a signed P2PKHPay to Public Key Hash, the standard script that locks coins to an address transaction up to a BRC-100BSV Request for Comments 100, the standard interface between apps and wallets wallet interface and overlay servicesBuilt from topic managers, which decide what is admitted, and lookup services, which query what was admitted.. The docs and examples live in the Go repositories, and this page links them.

What the SDK includes

The module is github.com/bsv-blockchain/go-sdk. Each area below is a package under that path:

AreaPackages
Keys and cryptographyprimitives/ec, primitives/aesgcm, compat/bip32, compat/bip39, compat/ecies, message
Script and templatesscript, transaction/template/p2pkh
Transactions and feestransaction
Proofsspv, with BEEFBackground Evaluation Extended Format (BRC-62), a transaction sent with its proofs support in transaction
Broadcasting and chain trackingtransaction/broadcaster, transaction/chaintracker
Wallet interfacewallet, with the BRC-100 interface and ProtoWallet
Authenticationauth
Overlay services, identity and storageoverlay, registry, identity, kvstore, storage

Get started

Add the SDK to a Go module, then run a first program that signs a transaction and prints it, without touching the network.

Create a module and add the SDK

This page was written against go-sdk v1.7.3, which needs Go 1.26 or newer. In a new folder, create a module and add the SDK:

go mod init example.com/bsv-go
go get github.com/bsv-blockchain/go-sdk

The last line of the output names the version that was added:

go: creating new go.mod: module example.com/bsv-go
go: added github.com/bsv-blockchain/go-sdk v1.7.3

Create main.go

Create main.go in the module folder. The program builds and signs a transaction on your computer, with a key, a locking scriptThe part of a transaction output that sets the condition to spend it, an input, an output and a signature. It makes no network call and spends no coins.

The program generates a private key on each run and never saves it. Keep a private key that holds real funds out of your source code and out of version control.

main.go
package main

import (
	"fmt"
	"log"

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

func main() {
	priv, err := ec.NewPrivateKey()
	if err != nil {
		log.Fatal(err)
	}
	address, err := script.NewAddressFromPublicKey(priv.PubKey(), false)
	if err != nil {
		log.Fatal(err)
	}
	lockingScript, err := p2pkh.Lock(address)
	if err != nil {
		log.Fatal(err)
	}

	unlocker, err := p2pkh.Unlock(priv, nil)
	if err != nil {
		log.Fatal(err)
	}
	tx := transaction.NewTransaction()
	err = tx.AddInputFrom(
		"0000000000000000000000000000000000000000000000000000000000000000",
		0,
		lockingScript.String(),
		10000,
		unlocker,
	)
	if err != nil {
		log.Fatal(err)
	}
	if err := tx.PayToAddress(address.AddressString, 9000); err != nil {
		log.Fatal(err)
	}
	if err := tx.Sign(); err != nil {
		log.Fatal(err)
	}

	fmt.Println("Transaction ID:", tx.TxID())
	fmt.Println("Raw hex:", tx.Hex())
}

Run the program

In the module folder, run go mod tidy once, so Go records the packages the code imports. Without it, go run stops with a missing go.sum entry error. Then run the program:

go mod tidy
go run .

The program prints the transaction ID and the signed transaction in hex. Both change on every run, because the key is new each time:

Transaction ID: 764d9d730e316b6eeb0d12c221f189d2f1a88a51d94c37c8b0b94da579b01e92
Raw hex: 0100000001000000000000000000000000000000000000000000000000000000000000000000000000...

These parts of main.go need a closer look:

  • NewAddressFromPublicKey(priv.PubKey(), false) derives a testnet address from the public key. true gives a Mainnet address.
  • AddInputFrom describes the output the input spends: its transaction ID, its index, its locking script as a hex string and its value in satoshisThe smallest unit of BitcoinSV (BSV). 100,000,000 satoshis make 1 BSV.. Here the output exists only in the program, so the transaction ID is a placeholder of zeros. To spend a real output, use the values of one of your own UTXOsUnspent transaction output.
  • p2pkh.Unlock(priv, nil) gives the input a signing template, and tx.Sign() signs every input that has one.
  • PayToAddress adds an output of 9,000 satoshis. The 1,000 satoshis left between the input and the output are the fee.

A broadcast transaction cannot be undone, and the broadcaster examples in the repository send to Mainnet. Test on testnet before you use Mainnet.

To send a transaction, use a broadcaster from the transaction/broadcaster package. The transaction in main.go cannot be broadcast, because it spends an output that exists only in the program. The WhatsOnChain broadcaster takes a Network field, and broadcaster.WOCTestnet selects testnet. For the broadcaster BSV Association runs, see Broadcast transactions with BSV Broadcaster.

Find the docs and examples

The docs and examples live in the Go repositories, next to the code.

Docs and repositories

Start from these repositories and docs:

Examples you can run

Each of these folders in docs/examples holds a small program for one task:

TaskExample folder
Build and sign a P2PKH transactioncreate_simple_tx
Put data in a transaction with OP_RETURNcreate_tx_with_op_return
Derive a child key with BRC-42BSV Key Derivation Schemederive_child
Generate an HD keygenerate_hd_key
Encrypt a message for one recipientecies_single
Verify a BEEF structureverify_beef

To learn more about the SDKs on the BSV blockchain, review these articles: