Duration: 75 minutes
Prerequisites: Completed “Transaction Types and Data” tutorial, Node.js, basic TypeScript knowledge
WalletClient options for transaction controlThis tutorial builds on your knowledge of basic WalletClient usage to explore advanced transaction construction patterns. You’ll learn how to create sophisticated transactions that handle multiple inputs and outputs, optimize fees, and manage UTXOs effectively for production applications.
WalletClient OptionsThe createAction method supports many advanced options through the options parameter. Let’s explore these capabilities:
import { WalletClient } from '@bsv/sdk'
async function exploreAdvancedOptions() {
try {
const wallet = new WalletClient('auto', 'localhost')
// Authenticate with the wallet
const { authenticated } = await wallet.isAuthenticated()
if (!authenticated) {
await wallet.waitForAuthentication()
}
// Create a transaction with advanced options
const actionResult = await wallet.createAction({
description: 'Advanced options demonstration',
outputs: [
{
satoshis: 100,
lockingScript: '006a0e416476616e636564206f7074696f6e73', // OP_RETURN "Advanced options"
outputDescription: 'Advanced options demo'
}
],
options: {
// Don't automatically sign and process - gives you more control
signAndProcess: false,
// Accept delayed broadcast for better fee optimization
acceptDelayedBroadcast: true,
// Return only the transaction ID to save bandwidth
returnTXIDOnly: false,
// Don't send the transaction immediately
noSend: true,
// Randomize output order for privacy
randomizeOutputs: true
}
})
console.log('Transaction created with advanced options:')
console.log('Signable transaction available for manual processing')
if (actionResult.signableTransaction) {
console.log('Transaction reference:', actionResult.signableTransaction.reference)
console.log('Transaction ready for signing')
}
} catch (error: any) {
console.error('Error:', error)
// Provide helpful troubleshooting
if (error.message?.includes('unlockingScript')) {
console.log('\nTroubleshooting: When specifying custom inputs, you must provide:')
console.log('- unlockingScript (valid hexadecimal string, not empty)')
console.log('- unlockingScriptLength (typically 107 for P2PKH)')
console.log('\nRecommendation: Let the wallet auto-select inputs by omitting the inputs array')
}
}
}
exploreAdvancedOptions().catch(console.error)
Multi-input transactions combine multiple UTXOs to fund larger outputs. The BSV TypeScript SDK provides two approaches:
Automatic Input Selection (Recommended): Let the wallet automatically select UTXOs by creating outputs that require more satoshis than any single UTXO can provide.
Manual Input Specification (Advanced): Explicitly specify which UTXOs to use as inputs. This requires providing complete unlocking script information and is typically only needed for specialized use cases.
import { WalletClient } from '@bsv/sdk'
async function createMultiInputTransaction() {
try {
const wallet = new WalletClient('auto', 'localhost')
const { authenticated } = await wallet.isAuthenticated()
if (!authenticated) {
await wallet.waitForAuthentication()
}
// First, let's see what UTXOs we have available (basket name is 'bsv-tutorial' for consistency with previous tutorials, where we created some outputs)
const { outputs } = await wallet.listOutputs({
basket: 'bsv-tutorial',
include: 'locking scripts',
limit: 10
})
console.log(`Found ${outputs.length} available outputs:`)
outputs.forEach((output, index) => {
console.log(` ${index + 1}. ${output.outpoint}: ${output.satoshis} satoshis (spendable: ${output.spendable})`)
})
// Check if we have enough UTXOs for a multi-input transaction
const spendableOutputs = outputs.filter(output => output.spendable && output.satoshis >= 100)
if (spendableOutputs.length < 2) {
console.log('Need at least 2 spendable outputs for this demo')
return
}
// Method 1: Automatic Input Selection (Recommended)
// Create a transaction that requires multiple inputs by using a large output amount
// The wallet will automatically select multiple UTXOs if needed
const totalAvailable = spendableOutputs.reduce((sum, output) => sum + output.satoshis, 0)
const largeAmount = Math.min(1500, Math.floor(totalAvailable * 0.8)) // Use 80% of available funds
console.log(`Creating transaction requiring ${largeAmount} satoshis (should trigger multi-input selection)`)
const actionResult = await wallet.createAction({
description: 'Multi-input transaction example',
outputs: [
{
satoshis: largeAmount,
lockingScript: '006a0c4d756c74692d696e707574', // OP_RETURN "Multi-input"
outputDescription: 'Multi-input demo output'
}
]
// No inputs specified - let wallet auto-select
})
console.log('Transaction created successfully!')
console.log('Transaction ID:', actionResult.txid)
console.log(`View on explorer: https://whatsonchain.com/tx/${actionResult.txid}`)
// Method 2: Manual Input Specification (Advanced)
// Manual input specification requires unlocking script details
// This is commented out as it requires proper unlocking script construction
/*
const manualActionResult = await wallet.createAction({
description: 'Manual multi-input transaction',
inputs: [
{
outpoint: spendableOutputs[0].outpoint,
unlockingScript: '00', // Placeholder - would need actual unlocking script
unlockingScriptLength: 107, // Typical P2PKH unlocking script length
inputDescription: 'First manually selected input'
},
{
outpoint: spendableOutputs[1].outpoint,
unlockingScript: '00', // Placeholder - would need actual unlocking script
unlockingScriptLength: 107, // Typical P2PKH unlocking script length
inputDescription: 'Second manually selected input'
}
],
outputs: [
{
satoshis: 150,
lockingScript: '006a104d616e75616c2d6d756c74692d696e707574', // OP_RETURN "Manual-multi-input"
outputDescription: 'Manual multi-input demo output'
}
]
})
*/
} catch (error: any) {
console.error('Error:', error)
// Provide helpful troubleshooting
if (error.message?.includes('unlockingScript')) {
console.log('\nTroubleshooting: When specifying custom inputs, you must provide:')
console.log('- unlockingScript (valid hexadecimal string, not empty)')
console.log('- unlockingScriptLength (typically 107 for P2PKH)')
console.log('\nRecommendation: Let the wallet auto-select inputs by omitting the inputs array')
}
}
}
createMultiInputTransaction().catch(console.error)
For businesses and applications that need to send multiple payments efficiently, batch processing reduces fees and blockchain footprint:
import { WalletClient } from '@bsv/sdk'
async function createBatchPayment() {
try {
const wallet = new WalletClient('auto', 'localhost')
const { authenticated } = await wallet.isAuthenticated()
if (!authenticated) {
await wallet.waitForAuthentication()
}
// Simulate multiple payment recipients
const payments = [
{ amount: 100, description: 'Payment to Alice', data: 'Invoice #001' },
{ amount: 150, description: 'Payment to Bob', data: 'Invoice #002' },
{ amount: 200, description: 'Payment to Carol', data: 'Invoice #003' }
]
// Create outputs for each payment
const outputs = payments.map((payment, index) => {
// Create OP_RETURN with payment data
const dataHex = Buffer.from(payment.data).toString('hex')
const dataLength = Buffer.from(payment.data).length
const dataLengthHex = dataLength.toString(16).padStart(2, '0')
const lockingScript = `006a${dataLengthHex}${dataHex}`
return {
satoshis: payment.amount,
lockingScript: lockingScript,
outputDescription: payment.description,
basket: 'payments', // Organize outputs in a specific basket
tags: ['batch-payment', `invoice-${index + 1}`] // Tag for easy tracking
}
})
// Create the batch transaction
const actionResult = await wallet.createAction({
description: 'Batch payment transaction',
outputs: outputs,
labels: ['batch-processing', 'business-payments'], // Labels for transaction tracking
options: {
randomizeOutputs: false // Keep payment order for accounting
}
})
if (actionResult.txid) {
console.log(`Batch payment transaction created: ${actionResult.txid}`)
console.log(`Processed ${payments.length} payments in a single transaction`)
console.log(`Total amount: ${payments.reduce((sum, p) => sum + p.amount, 0)} satoshis`)
console.log(`View on explorer: https://whatsonchain.com/tx/${actionResult.txid}`)
}
} catch (error: unknown) {
console.error('Error:', error)
}
}
createBatchPayment().catch(console.error)
Baskets provide powerful UTXO organization capabilities. Here’s how to use them for advanced transaction patterns:
import { WalletClient } from '@bsv/sdk'
async function advancedBasketManagement() {
try {
const wallet = new WalletClient('auto', 'localhost')
const { authenticated } = await wallet.isAuthenticated()
if (!authenticated) {
await wallet.waitForAuthentication()
}
// Create outputs in different baskets for different purposes
console.log('Creating specialized UTXO baskets...')
const actionResult = await wallet.createAction({
description: 'UTXO organization with baskets',
outputs: [
{
satoshis: 500,
lockingScript: '006a0c48696768207072696f72697479', // OP_RETURN "High priority"
outputDescription: 'High priority reserve',
basket: 'high-priority',
tags: ['reserve', 'urgent-use'],
customInstructions: 'Reserved for urgent transactions'
},
{
satoshis: 300,
lockingScript: '006a0d4d656469756d207072696f72697479', // OP_RETURN "Medium priority"
outputDescription: 'Medium priority operations',
basket: 'medium-priority',
tags: ['operations', 'daily-use']
},
{
satoshis: 200,
lockingScript: '006a0b4c6f77207072696f72697479', // OP_RETURN "Low priority"
outputDescription: 'Low priority batch',
basket: 'low-priority',
tags: ['batch', 'bulk-operations']
}
]
})
if (actionResult.txid) {
console.log(`Basket organization transaction: ${actionResult.txid}`)
console.log('Note: OP_RETURN outputs are unspendable by design (for data storage)')
console.log('Waiting for wallet to process new outputs...')
// Give the wallet a moment to process the new outputs
await new Promise(resolve => setTimeout(resolve, 2000))
}
// Now let's examine our organized UTXOs
console.log('\nExamining basket organization...')
console.log('Note: OP_RETURN outputs show spendable: false because they are data-only outputs')
const baskets = ['high-priority', 'medium-priority', 'low-priority']
for (const basketName of baskets) {
const { outputs, totalOutputs } = await wallet.listOutputs({
basket: basketName,
includeTags: true,
includeCustomInstructions: true,
limit: 10
})
console.log(`\n${basketName.toUpperCase()} Basket:`)
console.log(` Total outputs: ${totalOutputs}`)
if (totalOutputs === 0) {
console.log(` Note: No outputs found. This could be because:`)
console.log(` - Outputs need confirmation time`)
console.log(` - Wallet needs time to process new baskets`)
console.log(` - OP_RETURN outputs might not be tracked as spendable UTXOs`)
}
outputs.forEach((output, index) => {
console.log(` Output ${index + 1}:`)
console.log(` Outpoint: ${output.outpoint}`)
console.log(` Amount: ${output.satoshis} satoshis`)
console.log(` Spendable: ${output.spendable}`)
if (output.tags) {
console.log(` Tags: ${output.tags.join(', ')}`)
}
if (output.customInstructions) {
console.log(` Instructions: ${output.customInstructions}`)
}
})
}
// Add processing delay
await new Promise(resolve => setTimeout(resolve, 5000));
} catch (error: unknown) {
console.error('Error:', error)
}
}
advancedBasketManagement().catch(console.error)
Sometimes you need to create transactions that depend on previous ones. Here’s how to handle transaction chaining:
import { WalletClient } from '@bsv/sdk'
async function createTransactionChain() {
try {
const wallet = new WalletClient('auto', 'localhost')
const { authenticated } = await wallet.isAuthenticated()
if (!authenticated) {
await wallet.waitForAuthentication()
}
console.log('Creating transaction chain...')
console.log('Transaction chaining allows you to create a series of transactions that depend on each other.')
console.log('This is useful for scenarios where you need to ensure that a transaction is only processed after a previous one has been confirmed.')
console.log('In this example, we will create two transactions: the first one creates an output, and the second one spends that output.')
// First transaction - creates outputs for the chain
const firstTx = await wallet.createAction({
description: 'Chain starter transaction',
outputs: [
{
satoshis: 400,
lockingScript: '006a0d436861696e207374617274657220', // OP_RETURN "Chain starter"
outputDescription: 'Chain starter output',
basket: 'chain-demo',
tags: ['chain', 'step-1']
}
],
options: {
acceptDelayedBroadcast: true // Allow some delay for better fee optimization
}
})
if (!firstTx.txid) {
console.log('First transaction failed')
return
}
console.log(`First transaction: ${firstTx.txid}`)
// Wait a moment for the transaction to be processed
await new Promise(resolve => setTimeout(resolve, 2000))
// Second transaction - demonstrates chaining with sendWith option
// Note: We use automatic input selection rather than manual specification
// Manual input specification requires unlockingScript and unlockingScriptLength
// which adds complexity for tutorial purposes
const secondTx = await wallet.createAction({
description: 'Chain continuation transaction',
outputs: [
{
satoshis: 150,
lockingScript: '006a0c436861696e20636f6e74696e756174696f6e', // OP_RETURN "Chain continuation"
outputDescription: 'Chain continuation output',
basket: 'chain-demo',
tags: ['chain', 'step-2']
}
],
options: {
sendWith: [firstTx.txid] // Ensure this transaction is sent with the first one
}
})
if (secondTx.txid) {
console.log(`Second transaction: ${secondTx.txid}`)
console.log('Transaction chain completed successfully')
}
} catch (error: unknown) {
console.error('Error in transaction chain:', error)
}
}
createTransactionChain().catch(console.error)
For high-throughput applications, consider these optimization techniques:
import { WalletClient } from '@bsv/sdk'
async function optimizedTransactionPatterns() {
try {
const wallet = new WalletClient('auto', 'localhost')
const { authenticated } = await wallet.isAuthenticated()
if (!authenticated) {
await wallet.waitForAuthentication()
}
// Strategy 1: Pre-allocate UTXOs for different purposes
console.log('Pre-allocating UTXOs for optimal performance...')
const allocationTx = await wallet.createAction({
description: 'UTXO pre-allocation for performance',
outputs: [
// Create multiple small UTXOs for frequent operations
...Array(5).fill(null).map((_, i) => ({
satoshis: 200,
lockingScript: `006a0f507265616c6c6f636174656420${i.toString(16).padStart(2, '0')}`, // "Preallocated" + index
outputDescription: `Pre-allocated UTXO ${i + 1}`,
basket: 'pre-allocated',
tags: ['performance', 'ready-to-use']
}))
],
options: {
acceptDelayedBroadcast: true
}
})
if (allocationTx.txid) {
console.log(`Pre-allocation transaction: ${allocationTx.txid}`)
}
// Strategy 2: Batch multiple operations efficiently
await new Promise(resolve => setTimeout(resolve, 3000))
const operations = [
{ type: 'data', content: 'Operation 1' },
{ type: 'data', content: 'Operation 2' },
{ type: 'data', content: 'Operation 3' }
]
const batchOutputs = operations.map((op, index) => {
const dataHex = Buffer.from(op.content).toString('hex')
const dataLength = Buffer.from(op.content).length
const dataLengthHex = dataLength.toString(16).padStart(2, '0')
return {
satoshis: 100,
lockingScript: `006a${dataLengthHex}${dataHex}`,
outputDescription: `Batch operation ${index + 1}`,
basket: 'operations',
tags: ['batch', `op-${index + 1}`]
}
})
// Use pre-allocated UTXOs for the batch
const { outputs: preAllocated } = await wallet.listOutputs({
basket: 'pre-allocated',
limit: 3
})
console.log(`Found ${preAllocated.length} pre-allocated UTXOs`)
if (preAllocated.length > 0) {
// Let the wallet automatically select inputs instead of manual specification
const batchTx = await wallet.createAction({
description: 'Optimized batch operation',
outputs: batchOutputs,
options: {
randomizeOutputs: false, // Maintain order for processing
acceptDelayedBroadcast: true
}
})
if (batchTx.txid) {
console.log(`Optimized batch transaction: ${batchTx.txid}`)
console.log(`Processed ${operations.length} operations efficiently`)
}
}
} catch (error: unknown) {
console.error('Optimization error:', error)
}
}
optimizedTransactionPatterns().catch(console.error)
You’ve now mastered advanced transaction construction with the BSV TypeScript SDK’s WalletClient. You can:
WalletClient features like baskets, tags, and optionsThese techniques enable you to build production-ready applications that efficiently manage Bitcoin transactions while maintaining reliability and performance.
Check out specialized tutorials for your specific use case