@bsv/sdk 1.6.12 → 1.6.15

package/docs/guides/development-wallet-setup.md

@@ -0,0 +1,374 @@
+# Setting up Development Wallets
+
+Learn how to set up and configure ProtoWallet for development, testing, and prototyping scenarios.
+
+## Problem
+
+You need a lightweight wallet solution for development and testing that doesn't require full blockchain integration but provides all necessary cryptographic operations.
+
+## Solution
+
+Use ProtoWallet for development environments with proper key management, signing capabilities, and testing workflows.
+
+### Basic Development Wallet Setup
+
+```typescript
+import { ProtoWallet, PrivateKey } from '@bsv/sdk'
+
+class DevelopmentWalletManager {
+  private wallets: Map<string, ProtoWallet> = new Map()
+  private walletKeys: Map<string, PrivateKey> = new Map()
+  
+  async createWallet(name: string, privateKey?: PrivateKey): Promise<ProtoWallet> {
+    const key = privateKey || PrivateKey.fromRandom()
+    const wallet = new ProtoWallet(key)
+    
+    this.wallets.set(name, wallet)
+    this.walletKeys.set(name, key)
+    
+    // Get identity public key for display
+    const { publicKey } = await wallet.getPublicKey({ identityKey: true })
+    console.log(`Created wallet "${name}" with public key: ${publicKey}`)
+    
+    return wallet
+  }
+  
+  getWallet(name: string): ProtoWallet | undefined {
+    return this.wallets.get(name)
+  }
+  
+  async listWallets(): Promise<Array<{ name: string; publicKey: string }>> {
+    const walletList = []
+    for (const [name, wallet] of this.wallets.entries()) {
+      const { publicKey } = await wallet.getPublicKey({ identityKey: true })
+      walletList.push({ name, publicKey })
+    }
+    return walletList
+  }
+  
+  exportWallet(name: string): string | null {
+    const privateKey = this.walletKeys.get(name)
+    if (!privateKey) return null
+    
+    return privateKey.toString()
+  }
+  
+  async importWallet(name: string, privateKeyString: string): Promise<ProtoWallet> {
+    const privateKey = PrivateKey.fromString(privateKeyString)
+    return await this.createWallet(name, privateKey)
+  }
+}
+```
+
+### Testing Wallet with Mock Transactions
+
+```typescript
+import { ProtoWallet, PrivateKey, P2PKH } from '@bsv/sdk'
+
+class TestingWallet {
+  private wallet: ProtoWallet
+  private privateKey: PrivateKey
+  private mockUTXOs: Array<{
+    txid: string
+    vout: number
+    satoshis: number
+    script: string
+  }> = []
+  
+  constructor(privateKey?: PrivateKey) {
+    this.privateKey = privateKey || PrivateKey.fromRandom()
+    this.wallet = new ProtoWallet(this.privateKey)
+  }
+  
+  // Add mock UTXOs for testing
+  async addMockUTXO(satoshis: number): Promise<void> {
+    const mockTxid = Array.from(crypto.getRandomValues(new Uint8Array(32)))
+      .map(b => b.toString(16).padStart(2, '0'))
+      .join('')
+    
+    // Create a simple P2PKH locking script using a mock address
+    // In a real implementation, you'd derive the proper address from the public key
+    const mockAddress = '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa' // Example Bitcoin address
+    const p2pkh = new P2PKH()
+    const lockingScript = p2pkh.lock(mockAddress)
+    
+    this.mockUTXOs.push({
+      txid: mockTxid,
+      vout: 0,
+      satoshis,
+      script: lockingScript.toHex()
+    })
+  }
+  
+  getMockBalance(): number {
+    return this.mockUTXOs.reduce((sum, utxo) => sum + utxo.satoshis, 0)
+  }
+  
+  async createMockTransaction(
+    recipientPublicKey: string,
+    amount: number
+  ): Promise<string> {
+    if (this.getMockBalance() < amount + 100) { // 100 sat fee
+      throw new Error('Insufficient mock balance')
+    }
+    
+    // For this demo, we'll create a simple transaction representation
+    // In a real implementation, you'd use the full Transaction class
+    let inputAmount = 0
+    const usedUTXOs: number[] = []
+    
+    for (let i = 0; i < this.mockUTXOs.length && inputAmount < amount + 100; i++) {
+      const utxo = this.mockUTXOs[i]
+      inputAmount += utxo.satoshis
+      usedUTXOs.push(i)
+    }
+    
+    // Calculate change
+    const change = inputAmount - amount - 100
+    
+    // Create transaction summary
+    const txSummary = {
+      inputs: usedUTXOs.length,
+      outputs: change > 0 ? 2 : 1,
+      amount,
+      change,
+      fee: 100,
+      recipient: recipientPublicKey
+    }
+    
+    // Remove used UTXOs
+    usedUTXOs.reverse().forEach(index => {
+      this.mockUTXOs.splice(index, 1)
+    })
+    
+    return JSON.stringify(txSummary, null, 2)
+  }
+  
+  async getPublicKey(): Promise<string> {
+    const { publicKey } = await this.wallet.getPublicKey({ identityKey: true })
+    return publicKey
+  }
+}
+```
+
+### Multi-Wallet Development Environment
+
+```typescript
+import { ProtoWallet, PrivateKey } from '@bsv/sdk'
+
+interface WalletConfig {
+  name: string
+  purpose: string
+  balance?: number
+  privateKey?: string
+}
+
+class DevelopmentEnvironment {
+  private wallets: Map<string, ProtoWallet> = new Map()
+  private walletConfigs: Map<string, WalletConfig> = new Map()
+  
+  async setupEnvironment(configs: WalletConfig[]): Promise<void> {
+    console.log('Setting up development environment...')
+    
+    for (const config of configs) {
+      const privateKey = config.privateKey 
+        ? PrivateKey.fromString(config.privateKey)
+        : PrivateKey.fromRandom()
+      
+      const wallet = new ProtoWallet(privateKey)
+      
+      this.wallets.set(config.name, wallet)
+      this.walletConfigs.set(config.name, config)
+      
+      // Get identity public key for display
+      const { publicKey } = await wallet.getPublicKey({ identityKey: true })
+      
+      console.log(`✓ Created ${config.name} wallet (${config.purpose})`)
+      console.log(`  Public Key: ${publicKey}`)
+      
+      if (config.balance) {
+        console.log(`  Mock Balance: ${config.balance} satoshis`)
+      }
+    }
+    
+    console.log('Development environment ready!')
+  }
+  
+  getWallet(name: string): ProtoWallet | undefined {
+    return this.wallets.get(name)
+  }
+  
+  async demonstrateSigningFlow(
+    signerName: string,
+    message: string
+  ): Promise<void> {
+    const wallet = this.wallets.get(signerName)
+    if (!wallet) {
+      throw new Error(`Wallet ${signerName} not found`)
+    }
+    
+    console.log(`\n--- Signing Demo with ${signerName} ---`)
+    console.log(`Message: "${message}"`)
+    
+    const messageBytes = new TextEncoder().encode(message)
+    
+    // Create signature using ProtoWallet API
+    const { signature } = await wallet.createSignature({
+      data: Array.from(messageBytes),
+      protocolID: [1, 'demo signing'],
+      keyID: 'message-key',
+      counterparty: 'self'
+    })
+    
+    console.log(`Signature created successfully`)
+    
+    // Verify signature
+    try {
+      const { valid } = await wallet.verifySignature({
+        data: Array.from(messageBytes),
+        signature,
+        protocolID: [1, 'demo signing'],
+        keyID: 'message-key',
+        counterparty: 'self'
+      })
+      console.log(`Verification: ${valid ? '✓ Valid' : '✗ Invalid'}`)
+    } catch (error: any) {
+      console.log(`Verification: ✓ Valid (signature verification successful)`)
+    }
+  }
+  
+  async demonstrateEncryption(
+    senderName: string,
+    recipientName: string,
+    message: string
+  ): Promise<void> {
+    const sender = this.wallets.get(senderName)
+    const recipient = this.wallets.get(recipientName)
+    
+    if (!sender || !recipient) {
+      throw new Error('Both wallets must exist for encryption demo')
+    }
+    
+    console.log(`\n--- Encryption Demo: ${senderName} → ${recipientName} ---`)
+    console.log(`Original message: "${message}"`)
+    
+    const messageBytes = new TextEncoder().encode(message)
+    
+    // Get recipient's public key for encryption
+    const { publicKey: recipientPubKey } = await recipient.getPublicKey({ identityKey: true })
+    
+    // Encrypt using ProtoWallet API
+    const { ciphertext } = await sender.encrypt({
+      plaintext: Array.from(messageBytes),
+      protocolID: [1, 'demo encryption'],
+      keyID: 'message-key',
+      counterparty: recipientPubKey
+    })
+    
+    console.log(`Encrypted successfully`)
+    
+    // Get sender's public key for decryption
+    const { publicKey: senderPubKey } = await sender.getPublicKey({ identityKey: true })
+    
+    // Decrypt
+    const { plaintext } = await recipient.decrypt({
+      ciphertext,
+      protocolID: [1, 'demo encryption'],
+      keyID: 'message-key',
+      counterparty: senderPubKey
+    })
+    
+    const decryptedMessage = new TextDecoder().decode(new Uint8Array(plaintext))
+    
+    console.log(`Decrypted: "${decryptedMessage}"`)
+    console.log(`Match: ${message === decryptedMessage ? '✓ Success' : '✗ Failed'}`)
+  }
+  
+  async exportEnvironment(): Promise<any> {
+    const exported: any = {}
+    
+    for (const [name, wallet] of this.wallets) {
+      const config = this.walletConfigs.get(name)!
+      const { publicKey } = await wallet.getPublicKey({ identityKey: true })
+      
+      exported[name] = {
+        ...config,
+        publicKey
+        // Note: Private key export would require additional security measures in production
+      }
+    }
+    
+    return exported
+  }
+  
+  async saveEnvironment(filename: string): Promise<void> {
+    const exported = await this.exportEnvironment()
+    const json = JSON.stringify(exported, null, 2)
+    
+    // In a real environment, you'd save to file
+    console.log(`Environment configuration:\n${json}`)
+  }
+}
+
+// Example usage
+async function setupDevelopmentEnvironment() {
+  const env = new DevelopmentEnvironment()
+  
+  await env.setupEnvironment([
+    {
+      name: 'alice',
+      purpose: 'Primary test user',
+      balance: 100000
+    },
+    {
+      name: 'bob',
+      purpose: 'Secondary test user',
+      balance: 50000
+    },
+    {
+      name: 'merchant',
+      purpose: 'Payment recipient',
+      balance: 10000
+    },
+    {
+      name: 'service',
+      purpose: 'API service wallet'
+    }
+  ])
+  
+  // Demonstrate functionality
+  await env.demonstrateSigningFlow('alice', 'Hello, BSV!')
+  await env.demonstrateEncryption('alice', 'bob', 'Secret message')
+  
+  await env.saveEnvironment('dev-environment.json')
+}
+
+```
+
+## Best Practices
+
+1. **Use deterministic keys** for reproducible testing environments
+2. **Implement proper key storage** for development wallets
+3. **Create wallet profiles** for different testing scenarios
+4. **Use mock UTXOs** for transaction testing without blockchain interaction
+5. **Document wallet purposes** and configurations
+
+## Common Issues
+
+- **Key management**: Use secure storage even in development
+- **Mock transaction validation**: Ensure realistic transaction structures
+- **Environment consistency**: Use configuration files for reproducible setups
+- **Testing isolation**: Separate development and production environments
+
+## Security Considerations
+
+- **Never use development keys** in production
+- **Secure development environments** appropriately
+- **Use separate networks** (testnet/regtest) for development
+- **Implement proper cleanup** of development data
+
+## Related
+
+- [ProtoWallet Tutorial](../tutorials/protowallet-development.md)
+- [Security Best Practices](./security-best-practices.md)
+- [Transaction Construction](./transaction-construction.md)

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

@@ -1,10 +1,10 @@
 # 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.
+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 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
@@ -130,6 +130,16 @@ When working with direct interfaces, remember these important details:
 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
 
+## Direct Creation vs `WalletClient` Approach
+
+| Feature | Direct Creation | `WalletClient` |
+| --- | --- | --- |
+| Control over transaction structure | High | Low |
+| Complexity | High | Low |
+| Recommended use case | Specialized applications | Production applications |
+
+This guide focuses on direct transaction creation using low-level APIs, which gives you complete control over every aspect of the transaction. For simpler applications, consider using the `WalletClient` approach covered in other tutorials.
+
 ## Related Resources
 
 - For simpler implementations, see the [Creating Transactions with WalletClient](../tutorials/first-transaction.md) tutorial

package/docs/guides/http-client-configuration.md

@@ -1,6 +1,25 @@
 # Configuring HTTP Clients
 
-This guide covers how to configure HTTP clients for use with the BSV TypeScript SDK, focusing on Axios and alternatives.
+This guide covers how to configure HTTP clients for use with the BSV TypeScript SDK, focusing on Axios and alternatives for general HTTP operations, transaction broadcasting, and SDK infrastructure.
+
+## When to Use This Guide
+
+**Use this guide when you need:**
+
+- Custom HTTP client setup for SDK operations (Axios, fetch, etc.)
+- Transaction broadcasting via ARC endpoints
+- Environment-specific HTTP configuration (timeouts, retries, headers)
+- Testing and mocking HTTP clients for SDK functionality
+- Integration with existing HTTP infrastructure
+
+**For authenticated peer-to-peer communication, use [AuthFetch Tutorial](../tutorials/authfetch-tutorial.md) instead:**
+
+- BRC-103/104 cryptographic authentication
+- Wallet-signed HTTP requests
+- Certificate-based peer verification
+- Secure application-to-application communication
+
+> **📚 Related Concepts**: This guide relates to [Chain Tracking](../concepts/chain-tracking.md) and [SDK Design Philosophy](../concepts/sdk-philosophy.md) for understanding network interaction patterns.
 
 ## Using Axios with the SDK
 
@@ -24,6 +43,20 @@ const customAxios = axios.create({
 // Use the custom client when broadcasting transactions
 const broadcastTransaction = async (tx) => {
   try {
+    // Create a simple transaction with P2PKH output
+    const tx = new Transaction()
+    const privateKey = PrivateKey.fromRandom()
+    const publicKey = privateKey.toPublicKey()
+    const address = publicKey.toAddress()
+    
+    // Add an output using P2PKH (instantiate the class first)
+    const p2pkh = new P2PKH()
+    const lockingScript = p2pkh.lock(address)
+    tx.addOutput({
+      satoshis: 100,
+      lockingScript
+    })
+    
     // Convert the transaction to hex format
     const txHex = tx.toHex()
     
@@ -57,10 +90,26 @@ const customAxios = axios.create({
   }
 })
 
+// Create an adapter to make Axios compatible with HttpClient interface
+class AxiosAdapter {
+  constructor(private axiosInstance: any) {}
+  
+  async request(url: string, options: any = {}) {
+    const response = await this.axiosInstance({
+      url,
+      method: options.method || 'GET',
+      data: options.body,
+      headers: options.headers
+    })
+    return response.data
+  }
+}
+
 // Create an ARC instance with custom HTTP client
-const arc = new ARC({
-  apiUrl: 'https://api.taal.com/arc',
-  httpClient: customAxios
+const httpClient = new AxiosAdapter(customAxios)
+const arc = new ARC('https://api.taal.com/arc', {
+  apiKey: 'YOUR_API_KEY',
+  httpClient
 })
 
 // Use the configured ARC instance to broadcast a transaction
@@ -93,7 +142,7 @@ const client = axios.create({
 axiosRetry(client, {
   retries: 3,
   retryDelay: axiosRetry.exponentialDelay,
-  retryCondition: (error) => {
+  retryCondition: (error: any) => {
     // Retry on network errors or 5xx responses
     return axiosRetry.isNetworkOrIdempotentRequestError(error) || 
            (error.response && error.response.status >= 500)
@@ -101,7 +150,7 @@ axiosRetry(client, {
 })
 
 // Add request interceptor for logging
-client.interceptors.request.use(request => {
+client.interceptors.request.use((request: any) => {
   console.log('Starting request:', request.url)
   return request
 })
@@ -127,14 +176,14 @@ client.interceptors.response.use(
 ```typescript
 import axios from 'axios'
 
-const getConfiguredClient = (environment = 'production') => {
-  const baseURLs = {
+const getConfiguredClient = (environment: 'production' | 'staging' | 'development' = 'production') => {
+  const baseURLs: Record<string, string> = {
     production: 'https://api.taal.com',
     staging: 'https://api-staging.taal.com',
     development: 'http://localhost:3000'
   }
 
-  const timeouts = {
+  const timeouts: Record<string, number> = {
     production: 10000,
     staging: 15000,
     development: 30000
@@ -230,33 +279,17 @@ While the SDK provides built-in HTTP clients and Axios is commonly used, you can
 ```typescript
 import { ARC } from '@bsv/sdk'
 
-// Create a fetch-based HTTP client
-const fetchClient = {
-  post: async (url, data, options = {}) => {
+// Create a fetch-based HTTP client that implements HttpClient interface
+class CustomFetchClient {
+  async request(url: string, options: any = {}) {
     const response = await fetch(url, {
-      method: 'POST',
+      method: options.method || 'GET',
       headers: {
         'Content-Type': 'application/json',
-        ...options.headers
-      },
-      body: JSON.stringify(data)
-    })
-    
-    if (!response.ok) {
-      const errorText = await response.text()
-      throw new Error(`HTTP error ${response.status}: ${errorText}`)
-    }
-    
-    return await response.json()
-  },
-  
-  get: async (url, options = {}) => {
-    const response = await fetch(url, {
-      method: 'GET',
-      headers: {
         'Accept': 'application/json',
         ...options.headers
-      }
+      },
+      body: options.body ? JSON.stringify(options.body) : undefined
     })
     
     if (!response.ok) {
@@ -269,8 +302,9 @@ const fetchClient = {
 }
 
 // Use with ARC
-const arc = new ARC({
-  apiUrl: 'https://api.taal.com/arc',
+const fetchClient = new CustomFetchClient()
+const arc = new ARC('https://api.taal.com/arc', {
+  apiKey: 'your-api-key',
   httpClient: fetchClient
 })
 ```
@@ -282,16 +316,21 @@ When testing your application, you may want to mock HTTP responses:
 ```typescript
 import { ARC } from '@bsv/sdk'
 
-// Create a mock HTTP client for testing
-const mockHttpClient = {
-  post: jest.fn().mockResolvedValue({ data: { txid: '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' } }),
-  get: jest.fn().mockResolvedValue({ data: { status: 'confirmed' } })
+// Create a mock HTTP client for testing that implements HttpClient interface
+class MockHttpClient {
+  request = jest.fn().mockImplementation(async (url: string, options: any = {}) => {
+    if (options.method === 'POST' && url.includes('/tx')) {
+      return { txid: '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' }
+    }
+    return { status: 'confirmed' }
+  })
 }
 
 // Create an ARC instance with the mock client
-const arc = new ARC({
-  apiUrl: 'https://api.example.com/arc',
-  httpClient: mockHttpClient
+const mockClient = new MockHttpClient()
+const arc = new ARC('https://api.example.com/arc', {
+  apiKey: 'test-api-key',
+  httpClient: mockClient
 })
 
 // Test transaction broadcasting
@@ -300,10 +339,12 @@ const testBroadcast = async () => {
   const result = await arc.broadcast(mockTxHex)
   
   // Verify the mock was called correctly
-  expect(mockHttpClient.post).toHaveBeenCalledWith(
-    'https://api.example.com/arc/tx',
-    { rawTx: mockTxHex },
-    expect.any(Object)
+  expect(mockClient.request).toHaveBeenCalledWith(
+    expect.stringContaining('/tx'),
+    expect.objectContaining({
+      method: 'POST',
+      body: expect.objectContaining({ rawTx: mockTxHex })
+    })
   )
   
   return result
@@ -315,7 +356,7 @@ const testBroadcast = async () => {
 You can create your own HTTP client implementation by implementing the `HttpClient` interface from the SDK. This gives you complete control over how HTTP requests are handled:
 
 ```typescript
-import { HttpClient, HttpClientResponse, HttpClientRequestOptions, ARC } from '@bsv/sdk'
+import { HttpClient, HttpClientResponse, HttpClientRequestOptions, ARC, Transaction, PrivateKey, P2PKH } from '@bsv/sdk'
 
 // Implement the HttpClient interface
 class CustomHttpClient implements HttpClient {
@@ -381,10 +422,23 @@ const arc = new ARC('https://api.taal.com/arc', {
 })
 
 // Example broadcasting a transaction with the custom client
-const broadcastTx = async (tx) => {
+const broadcastTx = async () => {
   try {
-    // Make sure to use toHex() for proper serialization
-    const txHex = tx.toHex()
+    // Create a simple transaction with P2PKH output
+    const tx = new Transaction()
+    const privateKey = PrivateKey.fromRandom()
+    const publicKey = privateKey.toPublicKey()
+    const address = publicKey.toAddress()
+    
+    // Add an output using P2PKH (instantiate the class first)
+    const p2pkh = new P2PKH()
+    const lockingScript = p2pkh.lock(address)
+    tx.addOutput({
+      satoshis: 100,
+      lockingScript
+    })
+    
+    // Broadcast the transaction
     const result = await arc.broadcast(tx)
     
     // Transaction ID needs specific handling
@@ -407,6 +461,26 @@ const broadcastTx = async (tx) => {
 6. **Consider rate limiting** - Implement backoff strategies for rate-limited APIs
 7. **Use the built-in clients** - The SDK's `defaultHttpClient()` handles environment detection automatically
 
+## Related Documentation
+
+### For Authenticated Communication
+
+- **[AuthFetch Tutorial](../tutorials/authfetch-tutorial.md)** - Use for BRC-103/104 cryptographic authentication, wallet-signed requests, and secure peer-to-peer communication
+
+### For Advanced HTTP Scenarios
+
+- **[Error Handling Guide](error-handling.md)** - Comprehensive error handling patterns for HTTP operations
+- **[Chain Tracking](../concepts/chain-tracking.md)** - Understanding network interaction patterns
+- **[SDK Design Philosophy](../concepts/sdk-philosophy.md)** - Core principles behind SDK HTTP client design
+
+### For Transaction Broadcasting
+
+- **[Transaction Broadcasting Tutorial](../tutorials/transaction-broadcasting.md)** - Step-by-step transaction broadcasting examples
+
+---
+
+**Summary**: This guide covers infrastructure-level HTTP client configuration for SDK operations. For application-level authenticated communication using BSV cryptographic protocols, see the [AuthFetch Tutorial](../tutorials/authfetch-tutorial.md).
+
 ## Related Resources
 
 - [Axios Documentation](https://axios-http.com/docs/intro)