Your First Transaction

Overview

In this module, you'll create, sign, and broadcast your first BSV transaction. We'll show you two approaches: backend development using the SDK's Transaction class, and frontend development using the WalletClient. Both leverage the SDK's built-in features to handle complexity automatically.

Important Paradigm Note: The BSV SDK handles most transaction complexity for you - fee calculation, change outputs, UTXO selection, and broadcasting are all automated. You focus on what you want to accomplish, not the low-level mechanics.

Learning Objectives

By the end of this module, you will be able to:

  • Understand transaction structure conceptually

  • Build transactions using SDK's simplified methods

  • Use backend Transaction class for server-side applications

  • Use frontend WalletClient for browser-based applications

  • Broadcast transactions using SDK methods

  • Monitor transaction confirmations

Prerequisites

Before starting, ensure you have:

Transaction Structure (Conceptual)

Understanding transaction structure helps you reason about Bitcoin, even though the SDK handles the details.

What Happens Under the Hood

A BSV transaction consists of:

Transaction Flow

What the SDK Handles Automatically

The SDK takes care of:

  • Fee Calculation: Analyzes transaction size and applies fee rate

  • Change Outputs: Calculates and creates change back to your address

  • UTXO Selection: Chooses appropriate UTXOs for your transaction

  • Dust Limits: Ensures outputs meet minimum values

  • Script Templates: Manages locking and unlocking scripts

You just specify: what to send, how much, and to whom.

Backend Approach: Transaction Class

Use this approach for server-side applications, backend services, or when you need direct control over wallet management.

Simple Payment Transaction

What You Write vs What Happens

What You Write:

What the SDK Does:

  1. Validates the input UTXO

  2. Calculates transaction size

  3. Computes appropriate fee

  4. Determines change amount

  5. Creates change output (if needed)

  6. Checks dust limits

  7. Signs all inputs

  8. Serializes transaction

  9. Broadcasts to network

  10. Returns transaction ID

Complete Backend Example

Backend: Multiple Recipients

Sending to multiple recipients is simple - just add multiple outputs:

Frontend Approach: WalletClient

Use this approach for browser-based applications where the user's wallet (like Panda Wallet) handles all the complexity.

How WalletClient Works

WalletClient is a standardized interface that connects to user wallets. The wallet:

  • Manages private keys securely

  • Selects and manages UTXOs

  • Calculates fees

  • Signs transactions

  • Broadcasts to network

You just specify what you want to accomplish.

Simple Payment with WalletClient

Frontend: Complete Example with UI

Frontend: Request Payment from User

You can also request a payment from the user with a specific amount:

Broadcasting Transactions

Using SDK's Built-in Broadcast

The simplest way to broadcast is using the Transaction class's built-in method:

What tx.broadcast() does:

  • Serializes the transaction to hex

  • Connects to ARC (miner broadcasting service)

  • Submits transaction to the network

  • Returns confirmation with TXID

WalletClient Auto-Broadcast

With WalletClient, broadcasting is automatic:

Broadcast Options (Advanced)

If you need custom broadcast behavior:

Monitoring Transactions

Check Transaction Status

After broadcasting, you can check the transaction status:

Understanding Confirmations

Confirmations = number of blocks mined after your transaction's block

Confirmation Guidelines:

  • 0 confirmations: In mempool, waiting to be mined

  • 1 confirmation: Included in a block, generally safe

  • 6+ confirmations: Very secure, standard for larger amounts

Polling for Confirmations

Common Patterns

Pattern 1: Simple Payment

Backend:

Frontend:

Pattern 2: Batch Payments

Backend:

Frontend:

Pattern 3: Transaction with Data

You can embed data in transactions using OP_RETURN:

Error Handling

Common Errors and Solutions

Error: "Insufficient funds"

Cause: Not enough satoshis to cover payment + fees

Solution:

Error: "Transaction broadcast failed"

Cause: Invalid transaction or network issue

Solution:

Error: "UTXO already spent"

Cause: Trying to spend a UTXO that's already been used

Solution:

Best Practices for Error Handling

Testing on Testnet

Always Test First

Testnet Checklist

Before moving to mainnet:

Practice Exercises

Exercise 1: Simple Payment

Send 0.0001 BSV (10,000 satoshis) to another testnet address.

Backend approach:

Frontend approach:

Exercise 2: Batch Payment

Send different amounts to 3 recipients in a single transaction.

Exercise 3: Transaction Monitor

Create a function that monitors a transaction until it receives 3 confirmations.

Exercise 4: Error Recovery

Implement a payment function that handles common errors gracefully.

Key Takeaways

What the SDK Does for You

  • Fee Calculation: Automatically computes correct fees based on transaction size

  • Change Management: Creates change outputs when needed

  • UTXO Selection: Backend can select appropriate UTXOs (or use wallet for frontend)

  • Dust Limits: Ensures all outputs meet minimum values

  • Broadcasting: Handles network communication with miners

  • Verification: Validates transactions before broadcast

What You Focus On

  • Business Logic: What payments to make and when

  • User Experience: How users interact with transactions

  • Error Handling: How to handle edge cases gracefully

  • Application Flow: Integration with your app's workflow

Backend vs Frontend

Backend (Transaction class):

  • Direct control over transaction building

  • Manage your own UTXOs and keys

  • Server-side or programmatic access

  • Full flexibility

Frontend (WalletClient):

  • User's wallet handles everything

  • Better security (keys stay in wallet)

  • Simpler integration

  • Standard user experience

Next Steps

Congratulations! You've completed the Beginner Learning Path. You now know how to:

  • Set up a BSV development environment

  • Understand BSV blockchain fundamentals

  • Create and manage wallets

  • Build, sign, and broadcast transactions using SDK methods

Ready for more? Continue to the Intermediate Learning Path to learn about:

  • Complex transaction patterns

  • Custom Bitcoin Scripts

  • SPV verification

  • BRC standards implementation

  • Overlay services integration

Additional Resources

Last updated