@bsv/sdk 1.6.8 → 1.6.10

package/docs/concepts/verification.md

@@ -0,0 +1,219 @@
+# Transaction Verification
+
+Understanding how to verify Bitcoin transactions using the BSV TypeScript SDK.
+
+## What is Transaction Verification?
+
+Transaction verification ensures that Bitcoin transactions are valid and can be trusted:
+
+```typescript
+import { Transaction } from '@bsv/sdk'
+
+// Verify a transaction
+const isValid = await transaction.verify(chainTracker, {
+  merkleProof: proof,
+  blockHeader: header
+})
+```
+
+## Verification Levels
+
+### Basic Validation
+Check transaction structure and format:
+- Valid input/output formats
+- Correct serialization
+- Proper script syntax
+- Signature format validation
+
+### Script Execution
+Verify that unlocking scripts satisfy locking scripts:
+- Execute Bitcoin script opcodes
+- Validate signature operations
+- Check script conditions
+- Ensure proper stack state
+
+### SPV Verification
+Confirm transaction inclusion in the blockchain:
+- Verify merkle proofs
+- Validate block headers
+- Check proof of work
+- Confirm transaction position
+
+## SDK Verification Methods
+
+### Transaction.verify()
+Complete transaction verification:
+```typescript
+const result = await transaction.verify(chainTracker, {
+  merkleProof: merkleProof,
+  blockHeader: blockHeader,
+  maxMemoryLimit: 100000000
+})
+```
+
+### Script Verification
+Verify individual scripts:
+```typescript
+const isValid = unlockingScript.verify(
+  lockingScript,
+  transaction,
+  inputIndex
+)
+```
+
+### Signature Verification
+Check digital signatures:
+```typescript
+const publicKey = PrivateKey.fromWif(wif).toPublicKey()
+const isValid = publicKey.verify(messageHash, signature)
+```
+
+## Verification Options
+
+### Memory Limits
+Control script execution memory usage:
+```typescript
+const options = {
+  maxMemoryLimit: 50000000 // 50MB limit
+}
+```
+
+### Scripts-Only Mode
+Skip SPV verification for performance:
+```typescript
+const options = {
+  scriptsOnly: true
+}
+```
+
+### Custom Chain Tracker
+Use specific data sources:
+```typescript
+const customTracker = new WhatsOnChain('testnet')
+const isValid = await transaction.verify(customTracker)
+```
+
+## BEEF Verification
+
+BEEF format includes verification data:
+```typescript
+// BEEF transactions include proofs
+const beefTx = Transaction.fromHexBEEF(beefData)
+
+// Verify using included proofs
+const isValid = await beefTx.verify(chainTracker)
+```
+
+## Error Handling
+
+Common verification failures:
+- Invalid signatures
+- Script execution errors
+- Missing merkle proofs
+- Network connectivity issues
+
+```typescript
+try {
+  const isValid = await transaction.verify(chainTracker)
+  if (!isValid) {
+    console.log('Transaction verification failed')
+  }
+} catch (error) {
+  console.error('Verification error:', error.message)
+}
+```
+
+## Performance Considerations
+
+### Batch Verification
+Verify multiple transactions efficiently:
+```typescript
+const results = await Promise.all(
+  transactions.map(tx => tx.verify(chainTracker))
+)
+```
+
+### Caching
+Cache verification results:
+```typescript
+const verificationCache = new Map()
+
+if (!verificationCache.has(txid)) {
+  const result = await transaction.verify(chainTracker)
+  verificationCache.set(txid, result)
+}
+```
+
+## Security Best Practices
+
+### Always Verify
+- Verify transactions before trusting them
+- Check both script execution and SPV proofs
+- Validate input data before verification
+
+### Multiple Sources
+- Use multiple chain trackers for redundancy
+- Cross-check verification results
+- Implement fallback mechanisms
+
+### Resource Limits
+- Set appropriate memory limits
+- Timeout long-running verifications
+- Monitor verification performance
+
+## Common Use Cases
+
+### Payment Verification
+```typescript
+// Verify received payment
+const payment = Transaction.fromHex(paymentHex)
+const isValid = await payment.verify(chainTracker)
+
+if (isValid) {
+  // Process confirmed payment
+}
+```
+
+### Historical Transaction Audit
+```typescript
+// Verify old transactions
+for (const txHex of historicalTransactions) {
+  const tx = Transaction.fromHex(txHex)
+  const result = await tx.verify(chainTracker)
+  console.log(`Transaction ${tx.id()}: ${result ? 'Valid' : 'Invalid'}`)
+}
+```
+
+## Integration Patterns
+
+### Wallet Integration
+```typescript
+// Wallets typically handle verification
+const wallet = new WalletClient()
+const action = await wallet.createAction({
+  outputs: [/* outputs */]
+})
+// Wallet verifies before broadcasting
+```
+
+### Application Verification
+```typescript
+// Applications verify received transactions
+async function processIncomingTransaction(txHex: string) {
+  const tx = Transaction.fromHex(txHex)
+  
+  if (await tx.verify(chainTracker)) {
+    // Process verified transaction
+    await handleValidTransaction(tx)
+  } else {
+    // Reject invalid transaction
+    throw new Error('Invalid transaction received')
+  }
+}
+```
+
+## Next Steps
+
+- Learn about [SPV Verification](./spv-verification.md) concepts
+- Understand [Digital Signatures](./signatures.md) validation
+- Explore [BEEF Format](./beef.md) for efficient verification

package/docs/concepts/wallet-integration.md

@@ -0,0 +1,95 @@
+# Wallet Integration
+
+How the BSV TypeScript SDK connects with Bitcoin wallets and manages user authentication.
+
+## Wallet Connection Model
+
+The SDK uses a standardized approach to connect with Bitcoin wallets:
+
+```typescript
+import { WalletClient } from '@bsv/sdk'
+
+// Connect to a wallet
+const wallet = new WalletClient('https://wallet-url')
+
+// Authenticate with the wallet
+await wallet.authenticate()
+```
+
+## BRC-100 Compliance
+
+The SDK follows the BRC-100 standard for wallet communication:
+- **Standardized APIs**: Consistent interface across different wallets
+- **Authentication**: Secure identity verification
+- **Transaction Signing**: Wallet handles private key operations
+- **UTXO Management**: Wallet manages available funds
+
+## Authentication Flow
+
+1. **Connection**: Establish connection to wallet service
+2. **Identity**: Wallet provides user identity information
+3. **Capabilities**: Discover what the wallet can do
+4. **Authorization**: User grants permission for specific operations
+
+## Transaction Creation
+
+The wallet handles sensitive operations:
+
+```typescript
+// Create a transaction action
+const action = await wallet.createAction({
+  description: 'Payment transaction',
+  outputs: [{
+    satoshis: 1000,
+    lockingScript: recipientScript
+  }]
+})
+
+// Wallet signs and broadcasts automatically
+```
+
+## Key Benefits
+
+### Security
+- Private keys never leave the wallet
+- User controls transaction approval
+- Secure authentication protocols
+
+### User Experience
+- Familiar wallet interface
+- Consistent across applications
+- Single sign-on capabilities
+
+### Developer Simplicity
+- No key management complexity
+- Standardized APIs
+- Automatic UTXO handling
+
+## Wallet Types
+
+The SDK works with various wallet implementations:
+- **Desktop Wallets**: Local applications with full control
+- **Web Wallets**: Browser-based wallet services
+- **Mobile Wallets**: Smartphone applications
+- **Hardware Wallets**: Secure hardware devices
+
+## Error Handling
+
+Common wallet integration scenarios:
+- Wallet not available or offline
+- User denies transaction approval
+- Insufficient funds in wallet
+- Network connectivity issues
+
+## Best Practices
+
+- Always handle wallet connection failures gracefully
+- Provide clear transaction descriptions to users
+- Implement retry logic for network issues
+- Cache wallet capabilities to improve performance
+
+## Next Steps
+
+- Learn about [Chain Tracking](./chain-tracking.md) for network data
+- Understand [Key Management](./key-management.md) concepts
+- Explore [Trust Model](./trust-model.md) considerations

package/docs/guides/direct-transaction-creation.md

@@ -0,0 +1,137 @@
+# Creating Transactions with Direct Interfaces
+
+This guide demonstrates how to create Bitcoin SV transactions using the lower-level direct interfaces provided by the BSV TypeScript SDK. This approach gives you more control over transaction construction and is useful for specialized use cases where the WalletClient abstraction isn't suitable.
+
+## When to Use Direct Interfaces
+
+- When creating custom transaction types not supported by WalletClient
+- When you need precise control over UTXO selection
+- When building specialized applications like data storage services that require custom optimization
+- When integrating with systems that require direct management of transactions
+- For educational purposes to understand the underlying transaction structure
+
+## Basic Transaction Construction
+
+```typescript
+import { PrivateKey, P2PKH, Transaction } from '@bsv/sdk'
+
+async function createBasicTransaction() {
+  // Create a private key
+  const privateKey = PrivateKey.fromRandom()
+  console.log(`Private key WIF: ${privateKey.toWif()}`)
+  
+  // Derive the address
+  const address = privateKey.toAddress()
+  console.log(`Address: ${address.toString()}`)
+  
+  // Create a new transaction
+  const tx = new Transaction()
+  
+  // Add an output
+  tx.addOutput({
+    lockingScript: new P2PKH().lock(address),
+    satoshis: 1000
+  })
+  
+  // Serialize the transaction
+  const txHex = tx.toHex()
+  console.log(`Transaction (hex): ${txHex}`)
+  
+  // Get transaction ID as a hex string
+  const txid = Buffer.from(tx.id()).toString('hex')
+  console.log(`Transaction ID: ${txid}`)
+}
+```
+
+## Complete Transaction with Inputs and Outputs
+
+For a complete transaction that can be broadcast, you need to add inputs, calculate fees, and sign it:
+
+```typescript
+import { Transaction, PrivateKey, P2PKH, ARC } from '@bsv/sdk'
+
+async function createCompleteTransaction() {
+  // Set up your wallet
+  const privateKey = PrivateKey.fromWif('your_private_key_here')
+  const myAddress = privateKey.toAddress()
+  const recipientAddress = 'recipient_address_here'
+
+  // You need the hex of the source transaction
+  const sourceTxHex = '...' // Hex string of the source transaction
+  
+  // Create a transaction
+  const tx = new Transaction()
+  
+  // Add the input
+  tx.addInput({
+    sourceTransaction: Transaction.fromHex(sourceTxHex),
+    sourceOutputIndex: 0, // The output index you want to spend
+    unlockingScriptTemplate: new P2PKH().unlock(privateKey)
+  })
+  
+  // Add the recipient output
+  tx.addOutput({
+    lockingScript: new P2PKH().lock(recipientAddress),
+    satoshis: 100 // Amount to send
+  })
+  
+  // Add the change output back to our address
+  tx.addOutput({
+    lockingScript: new P2PKH().lock(myAddress),
+    change: true // SDK will automatically calculate the change amount
+  })
+  
+  // Calculate fee and sign the transaction
+  await tx.fee()
+  await tx.sign()
+  
+  // Get the transaction hex ready for broadcasting
+  const signedTxHex = tx.toHex()
+  console.log(`Signed transaction hex: ${signedTxHex}`)
+  
+  // Get the transaction ID
+  const txid = Buffer.from(tx.id()).toString('hex')
+  console.log(`Transaction ID: ${txid}`)
+}
+```
+
+## Broadcasting the Transaction
+
+To broadcast your signed transaction:
+
+```typescript
+import { ARC, NodejsHttpClient } from '@bsv/sdk'
+import https from 'https'
+
+async function broadcastTransaction(signedTx) {
+  // Create an HTTP client
+  const httpClient = new NodejsHttpClient(https)
+  
+  // Initialize the ARC client
+  const arc = new ARC('https://api.arc.taal.com', {
+    apiKey: 'your_api_key_here',
+    httpClient,
+    deploymentId: 'your-deployment-id'
+  })
+  
+  // Broadcast the transaction
+  const result = await signedTx.broadcast(arc)
+  console.log('Broadcast result:', result)
+}
+```
+
+## Key Implementation Details
+
+When working with direct interfaces, remember these important details:
+
+1. Use `toWif()` (lowercase 'f') not `toWIF()` for private key WIF format
+2. Use `toHex()` instead of `toString()` for transaction serialization
+3. Transaction IDs need to be converted from byte arrays: `Buffer.from(tx.id()).toString('hex')`
+4. For script objects, use `toHex()` or `toASM()` rather than `toString()`
+5. Method chaining doesn't work well with current API - use separate method calls
+
+## Related Resources
+
+- For simpler implementations, see the [Creating Transactions with WalletClient](../tutorials/first-transaction.md) tutorial
+- Learn about [Advanced Transaction Signing](./advanced-transaction-signing.md)
+- Explore [HTTP Client Configuration](./http-client-configuration.md) for optimizing API requests