BSV Ruby SDK

Welcome to the BSV Blockchain Libraries Project, the comprehensive Ruby SDK designed to provide 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.

Table of Contents

1. Acknowledgements
2. Objective
3. Getting Started
4. Features & Deliverables
5. Documentation
6. Contribution Guidelines
7. Support & Contacts
8. Licence

Acknowledgements

This Ruby SDK is a port of the official BSV Blockchain SDKs, which serve as its reference implementations. Primitives, script handling, and transaction logic are directly translated from them, adapted for Ruby idioms and conventions.

The reference SDKs:

• TypeScript SDK
• Go SDK
• Python SDK

These are maintained under the BSV Blockchain organisation and backed by the Bitcoin Association. The debt to their contributors is substantial — their clear, robust code made this port both feasible and consistent.

Objective

The BSV Blockchain Libraries Project aims to structure and maintain a middleware layer of the BSV Blockchain technology stack. By facilitating the development and maintenance of core libraries, it serves as an essential toolkit for developers looking to build on the BSV Blockchain.

This Ruby SDK brings maximum compatibility with the official SDK family to the Ruby ecosystem. It was born from a practical need: building an attestation gem (bsv-attest) required a complete, idiomatic Ruby implementation of BSV primitives, script handling, and transaction construction. Rather than wrapping FFI bindings or shelling out to other languages, the SDK implements everything in pure Ruby using only the standard library's OpenSSL bindings.

Getting Started

Requirements

• Ruby >= 2.7
• No external dependencies beyond Ruby's standard library (openssl)

Installation

Add to your Gemfile:

gem 'bsv-sdk'

Or install directly:

gem install bsv-sdk

Basic Usage

Create and sign a P2PKH transaction:

require 'bsv-sdk'

# Generate a new private key (or load from WIF)
priv_key = BSV::Primitives::PrivateKey.generate

# Derive the public key hash for locking scripts
pubkey_hash = priv_key.public_key.hash160
locking_script = BSV::Script::Script.p2pkh_lock(pubkey_hash)

# Create a transaction spending a UTXO
tx = BSV::Transaction::Transaction.new

# Add an input referencing a previous transaction output
input = BSV::Transaction::TransactionInput.new(
  prev_tx_id: source_txid_bytes,   # 32-byte binary txid of the UTXO
  prev_tx_out_index: 0
)
input.source_satoshis = 100_000
input.source_locking_script = locking_script
tx.add_input(input)

# Add an output sending to the same address (for demonstration)
tx.add_output(BSV::Transaction::TransactionOutput.new(
  satoshis: 90_000,
  locking_script: locking_script
))

# Sign the input using the P2PKH template
template = BSV::Transaction::P2PKH.new(priv_key)
tx.inputs[0].unlocking_script = template.sign(tx, 0)

# The signed transaction is ready to broadcast
puts tx.to_hex

Features & Deliverables

• Cryptographic Primitives — ECDSA signing with RFC 6979 deterministic nonces, Schnorr signatures, ECIES encryption/decryption, Bitcoin Signed Messages. All built on Ruby's stdlib OpenSSL.
• Key Management — BIP-32 HD key derivation, BIP-39 mnemonic generation (12/24-word phrases), WIF import/export, Base58Check encoding/decoding.
• Script Layer — Complete opcode set, script parsing and serialisation, type detection and predicates (p2pkh?, p2pk?, p2sh?, multisig?, op_return?), data extraction (pubkey hashes, script hashes, addresses), and a fluent builder API.
• Script Templates — Ready-made locking and unlocking script generators for P2PKH, P2PK, P2MS (multisig), and OP_RETURN.
• Transaction Construction — Input/output building, BIP-143 sighash computation (all SIGHASH types with FORKID), P2PKH signing, fee estimation.
• SPV Structures — Merkle path construction and verification, BEEF (Background Evaluation Extended Format) serialisation and deserialisation.
• Network Integration — ARC broadcaster for transaction submission, WhatsOnChain chain provider for UTXO queries and fee rates.
• Wallet — Simple wallet that sources UTXOs, estimates fees, funds and signs transactions.

Documentation

Documentation is forthcoming. In the meantime:

• Browse the spec/ directory for usage examples
• Read the CHANGELOG for release history
• Refer to the reference SDKs for architectural context: ts-sdk | go-sdk | py-sdk

Contribution Guidelines

Contributions are welcome — bug reports, feature requests, and pull requests.

1. Fork & Clone — Fork this repository and clone it locally.
2. Set Up — Run bundle install to install dependencies.
3. Branch — Create a new branch for your changes.
4. Test — Ensure all specs pass with bundle exec rake and lint passes with bundle exec rubocop.
5. Commit — Follow Conventional Commits for commit messages.
6. Pull Request — Open a pull request against master.

Support & Contacts

Maintainer: Simon Bettison

For questions, bug reports, or feature requests, please open an issue on GitHub.

Licence

Open BSV Licence Version 5

Thank you for being a part of the BSV Blockchain Libraries Project. Let's build the future of BSV Blockchain together!