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:
Completed Your First Wallet
A wallet with testnet BSV (get from MetaNet Desktop Wallet's faucet or BSV Discord)
Basic understanding of UTXOs and transactions
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:
Validates the input UTXO
Calculates transaction size
Computes appropriate fee
Determines change amount
Creates change output (if needed)
Checks dust limits
Signs all inputs
Serializes transaction
Broadcasts to network
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
Related Components
Related Code Features
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
WhatsOnChain Testnet - View your transactions
BSV Discord - Get free testnet BSV and community support
MetaNet Desktop Wallet - Has built-in testnet faucet
Transaction Format - Technical details
BSV SDK Documentation - Complete SDK reference
Last updated
