@bsv/sdk 1.6.9 → 1.6.11

package/docs/tutorials/advanced-transaction.md

@@ -0,0 +1,575 @@
+**Duration**: 75 minutes  
+**Prerequisites**: Completed "Transaction Types and Data" tutorial, Node.js, basic TypeScript knowledge  
+
+## Learning Goals
+- Master multi-input/multi-output transaction construction
+- Implement advanced fee calculation and optimization strategies
+- Handle change outputs efficiently
+- Use advanced `WalletClient` options for transaction control
+- Implement UTXO selection and management strategies
+- Handle complex transaction scenarios and error recovery
+
+## Introduction
+
+This 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.
+
+## Prerequisites
+
+- Complete the [Transaction Types and Data](./transaction-types.md) tutorial
+- Have a BRC-100 compliant wallet (such as the [MetaNet Desktop Wallet](https://metanet.bsvb.tech/)) installed and configured
+- Some BSV in your wallet
+- Understanding of Bitcoin transaction fundamentals
+
+## Advanced `WalletClient` Options
+
+The `createAction` method supports many advanced options through the `options` parameter. Let's explore these capabilities:
+
+```typescript
+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 Transaction Construction
+
+Multi-input transactions combine multiple UTXOs to fund larger outputs. The BSV TypeScript SDK provides two approaches:
+
+1. **Automatic Input Selection (Recommended)**: Let the wallet automatically select UTXOs by creating outputs that require more satoshis than any single UTXO can provide.
+
+2. **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.
+
+```typescript
+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)
+```
+
+## Batch Processing Multiple Payments
+
+For businesses and applications that need to send multiple payments efficiently, batch processing reduces fees and blockchain footprint:
+
+```typescript
+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)
+```
+
+## Advanced UTXO Management with Baskets
+
+Baskets provide powerful UTXO organization capabilities. Here's how to use them for advanced transaction patterns:
+
+```typescript
+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)
+```
+
+## Transaction Chaining and Dependencies
+
+Sometimes you need to create transactions that depend on previous ones. Here's how to handle transaction chaining:
+
+```typescript
+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)
+```
+
+
+## Performance Optimization Strategies
+
+For high-throughput applications, consider these optimization techniques:
+
+```typescript
+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)
+```
+
+
+
+## Conclusion
+
+You've now mastered advanced transaction construction with the BSV TypeScript SDK's `WalletClient`. You can:
+
+- Create sophisticated multi-input/multi-output transactions
+- Implement robust error handling and retry strategies
+- Optimize transaction patterns for performance
+- Use advanced `WalletClient` features like baskets, tags, and options
+- Handle complex scenarios like transaction chaining and batch processing
+
+These techniques enable you to build production-ready applications that efficiently manage Bitcoin transactions while maintaining reliability and performance.
+
+## Next Steps
+
+- Review the [Transaction Signing Methods](../guides/transaction-signing-methods.md) for custom signing scenarios
+- Check out specialized tutorials for your specific use case
+
+- Advanced transaction construction requires robust error handling for production applications. For comprehensive coverage of error handling patterns, retry mechanisms, and recovery strategies, see the dedicated [Error Handling Tutorial](./error-handling.md).
+
+
+## Additional Resources
+
+- [Wallet Reference](../reference/wallet.md)
+- [BSV Blockchain Documentation](https://docs.bsvblockchain.org/)
+- [MetaNet Desktop Wallet](https://metanet.bsvb.tech/)