Getting Started

Installation

Add the gem to your Gemfile:

gem 'bsv-sdk'

Then run:

bundle install

Or install directly:

gem install bsv-sdk

The SDK has no required external dependencies — it uses only Ruby’s standard library. Elliptic curve operations use a pure Ruby implementation with an optional native C extension for acceleration (see the secp256k1-native documentation). OpenSSL is used for hashing, HMAC, PBKDF2, and symmetric encryption.

Quick Start 

require 'bsv-sdk'

The SDK is organised into four modules:

Module Purpose
BSV::Primitives Keys, signing, hashing, encryption, HD keys
BSV::Script Script parsing, construction, templates
BSV::Transaction Building, signing, serialisation, BEEF
BSV::Network Broadcasting, chain tracking, SPV verification

Generate a Key Pair 

# Generate a new random private key
private_key = BSV::Primitives::PrivateKey.generate

# Export as WIF (Wallet Import Format)
wif = private_key.to_wif
#=> "L2huFnhCerfX..."

# Derive the public key and address
public_key = private_key.public_key
address = public_key.address
#=> "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"

Build a Simple Transaction

This example builds a P2PKH transaction that spends one input and creates two outputs: an OP_RETURN data carrier and a change output.

Transaction IDs: The SDK uses wtxid for wire-order binary (the native byte order of SHA-256d hashes) and dtxid for display-order hex (the reversed format shown by block explorers). Internally, everything is wire order — conversion to display order happens only at JSON and UI boundaries. See the wtxid/dtxid convention for the full rationale.

# Set up keys
private_key = BSV::Primitives::PrivateKey.generate
pubkey_hash = private_key.public_key.hash160
locking_script = BSV::Script::Script.p2pkh_lock(pubkey_hash)

# Create the transaction
tx = BSV::Transaction::Tx.new

# Add an input (referencing a previous UTXO)
input = BSV::Transaction::TransactionInput.new(
  prev_wtxid: BSV::Transaction::TransactionInput.wtxid_from_hex(
    '5884e5db9de218238671572340b207ee85b628074e7e467096c267266baf77a4'
  ),
  prev_tx_out_index: 0
)
input.source_satoshis = 1_000_000
input.source_locking_script = locking_script
tx.add_input(input)

# Add an OP_RETURN output (data carrier, zero satoshis)
tx.add_output(BSV::Transaction::TransactionOutput.new(
  satoshis: 0,
  locking_script: BSV::Script::Script.op_return('hello world'.b)
))

# Add a change output (send remaining funds back)
fee = BSV::Transaction::FeeModels::SatoshisPerKilobyte.new.compute_fee(tx)
tx.add_output(BSV::Transaction::TransactionOutput.new(
  satoshis: 1_000_000 - fee,
  locking_script: locking_script
))

# Sign the input
tx.sign(0, private_key)

# Broadcast via GorillaPool (Arcade protocol, public endpoint)
provider = BSV::Network::Providers::GorillaPool.default
result = provider.call(:broadcast, tx)
puts result.data['txid'] if result.http_success?  # display-order hex (ARC API boundary)

Using Templates for Signing

For transactions with multiple inputs, use unlocking script templates. This lets sign_all handle each input automatically:

tx = BSV::Transaction::Tx.new

# Create inputs with templates
input = BSV::Transaction::TransactionInput.new(
  prev_wtxid: BSV::Transaction::TransactionInput.wtxid_from_hex(utxo_txid),
  prev_tx_out_index: 0
)
input.source_satoshis = 50_000
input.source_locking_script = locking_script
input.unlocking_script_template = BSV::Transaction::P2PKH.new(private_key)
tx.add_input(input)

# Add outputs...

# Sign all inputs at once
tx.sign_all

Coming from TS or Go?

If you already know the TypeScript or Go BSV SDKs, most of the API is a direct translation to Ruby idioms. The common cases:

TS / Go Ruby Notes
key.toPublicKey() key.public_key Derived properties are bare nouns, not to_* methods
tx.getTxid() tx.dtxid Display-order hex; tx.wtxid for wire-order binary
input.setSourceSatoshis(5000) input.source_satoshis = 5000 Setters use assignment syntax
tx.toHex() tx.to_hex Format conversions keep to_
Transaction.fromBinary(data) Transaction.from_binary(data) Constructors use from_
script.isP2PKH() script.p2pkh? Boolean methods end in ?, drop is/has prefix
createAction({ description, inputs }) create_action(description:, inputs:) Options objects become keyword arguments

BRC-100 wire protocol methods are the exception — get_public_key, get_height, is_authenticated, list_outputs keep their protocol names because they are the protocol names. Don’t try to rename them.

For the full picture including edge cases and rationale, see Naming Conventions.

What’s Next

This site uses Just the Docs, a documentation theme for Jekyll.