@bsv/sdk 1.6.8 → 1.6.10

package/docs/concepts/beef.md

@@ -0,0 +1,84 @@
+# BEEF Format
+
+Bitcoin Extras Extension Format (BEEF) - an efficient way to package Bitcoin transactions with their verification data.
+
+## What is BEEF?
+
+BEEF is a standardized format that combines:
+- **Transaction Data**: The actual Bitcoin transaction
+- **Merkle Proofs**: SPV verification data
+- **Block Headers**: Chain validation information
+- **Metadata**: Additional context and references
+
+## BEEF in the SDK
+
+```typescript
+import { Transaction } from '@bsv/sdk'
+
+// Create transaction with BEEF data
+const tx = Transaction.fromHexBEEF(beefHex)
+
+// Serialize transaction to BEEF
+const beefData = transaction.toBEEF()
+
+// Verify transaction using included proofs
+const isValid = await tx.verify(chainTracker)
+```
+
+## Key Benefits
+
+### Efficiency
+- **Compact**: Includes only necessary verification data
+- **Self-Contained**: No external lookups required
+- **Batch Processing**: Multiple transactions in one package
+
+### SPV Integration
+- **Merkle Proofs**: Verify transaction inclusion
+- **Block Headers**: Validate proof of work
+- **Chain Context**: Understand transaction position
+
+### Interoperability
+- **Standardized**: Consistent format across applications
+- **Portable**: Easy to transmit and store
+- **Compatible**: Works with SPV clients
+
+## Use Cases
+
+### Transaction Broadcasting
+```typescript
+// Broadcast transaction with proof
+const beefTx = Transaction.fromHexBEEF(beefData)
+await beefTx.broadcast(arcConfig)
+```
+
+### Data Exchange
+- Share transactions between applications
+- Provide verification data to SPV clients
+- Archive transactions with proofs
+
+### Wallet Integration
+- Import transactions with full context
+- Verify historical transactions
+- Synchronize between devices
+
+## BEEF Structure
+
+The format includes:
+1. **Version**: BEEF format version
+2. **Transactions**: One or more Bitcoin transactions
+3. **Proofs**: Merkle proofs for each transaction
+4. **Headers**: Relevant block headers
+5. **Metadata**: Additional application data
+
+## Best Practices
+
+- Use BEEF for transactions that need verification
+- Include minimal necessary proof data
+- Validate BEEF structure before processing
+- Cache parsed BEEF data for performance
+
+## Next Steps
+
+- Learn about [SPV Verification](./spv-verification.md) concepts
+- Understand [Transaction Encoding](./transaction-encoding.md) formats
+- Explore [Chain Tracking](./chain-tracking.md) integration

package/docs/concepts/chain-tracking.md

@@ -0,0 +1,122 @@
+# Chain Tracking
+
+How the BSV TypeScript SDK interacts with the Bitcoin network to retrieve transaction and blockchain data.
+
+## Chain Tracker Concept
+
+A chain tracker provides access to Bitcoin blockchain data without running a full node:
+
+```typescript
+import { WhatsOnChain } from '@bsv/sdk'
+
+// Create a chain tracker
+const chainTracker = new WhatsOnChain('mainnet')
+
+// Get transaction data
+const txData = await chainTracker.getTransaction('txid')
+```
+
+## Key Functions
+
+### Transaction Lookup
+- Retrieve transaction details by ID
+- Get transaction status and confirmations
+- Access transaction inputs and outputs
+
+### UTXO Queries
+- Find unspent transaction outputs
+- Check UTXO availability and value
+- Retrieve UTXO locking scripts
+
+### Block Information
+- Get block headers and merkle proofs
+- Verify transaction inclusion in blocks
+- Access block timestamps and difficulty
+
+### Network Status
+- Check network connectivity
+- Monitor chain tip and height
+- Get fee rate recommendations
+
+## SPV Integration
+
+Chain trackers enable SPV (Simplified Payment Verification):
+- **Merkle Proofs**: Verify transaction inclusion without full blocks
+- **Header Chain**: Maintain block headers for proof verification
+- **Lightweight**: Minimal data requirements compared to full nodes
+
+## Multiple Providers
+
+The SDK supports multiple chain tracking services:
+
+```typescript
+// Primary and fallback providers
+const config = {
+  chainTracker: {
+    provider: 'WhatsOnChain',
+    network: 'mainnet',
+    fallbacks: ['GorillaPool', 'TAAL']
+  }
+}
+```
+
+## Benefits
+
+### Scalability
+- No need to store the entire blockchain
+- Fast startup and synchronization
+- Minimal storage requirements
+
+### Reliability
+- Multiple provider support
+- Automatic failover capabilities
+- Redundant data sources
+
+### Performance
+- Targeted data queries
+- Caching of frequently accessed data
+- Optimized for application needs
+
+## Common Patterns
+
+### Transaction Verification
+```typescript
+// Verify a transaction exists
+const exists = await chainTracker.getTransaction(txid)
+if (exists) {
+  // Transaction is confirmed on-chain
+}
+```
+
+### UTXO Validation
+```typescript
+// Check if UTXO is still unspent
+const utxo = await chainTracker.getUTXO(txid, outputIndex)
+if (utxo) {
+  // UTXO is available for spending
+}
+```
+
+## Error Handling
+
+Chain tracker operations can fail due to:
+- Network connectivity issues
+- Service provider downtime
+- Invalid transaction IDs
+- Rate limiting
+
+The SDK provides automatic retry and failover mechanisms.
+
+## Configuration
+
+Chain trackers can be configured for:
+- **Network**: Mainnet, testnet, or regtest
+- **Endpoints**: Custom service URLs
+- **Timeouts**: Request timeout settings
+- **Retry Logic**: Failure handling behavior
+
+## Next Steps
+
+- Understand [SPV Verification](./spv-verification.md) concepts
+- Learn about [BEEF Format](./beef.md) for efficient data exchange
+- Explore [Trust Model](./trust-model.md) considerations

package/docs/concepts/decentralized-identity.md

@@ -0,0 +1,184 @@
+# Decentralized Identity
+
+Understanding how decentralized identity works in BSV and why it matters for building trustless applications.
+
+## What is Decentralized Identity?
+
+Imagine a world where you control your own identity credentials, just like you control your own wallet. Instead of relying on Facebook, Google, or government agencies to verify who you are, you can prove your identity using cryptographic certificates that anyone can independently verify.
+
+This is the promise of decentralized identity: **self-sovereign identity** that puts users in control while maintaining security and trust.
+
+## Why Decentralized Identity Matters
+
+### The Problem with Centralized Identity
+Traditional identity systems have significant limitations:
+- **Single Points of Failure**: If the identity provider goes down, you lose access
+- **Privacy Concerns**: Companies collect and monetize your personal data
+- **Vendor Lock-in**: You can't easily move your identity between services
+- **Censorship Risk**: Providers can revoke your identity for any reason
+- **Data Breaches**: Centralized databases are attractive targets for hackers
+
+### The Decentralized Solution
+Decentralized identity addresses these issues by:
+- **User Control**: You own and manage your identity data
+- **No Central Authority**: No single entity controls the verification process
+- **Interoperability**: Your identity works across different applications
+- **Privacy by Design**: You choose what information to reveal and when
+- **Censorship Resistance**: No one can arbitrarily revoke your identity
+
+## How It Works in BSV
+
+### Identity Keys vs Transaction Keys
+BSV uses different types of keys for different purposes:
+
+**Identity Keys** are long-term, stable identifiers used for:
+- Establishing your digital identity
+- Signing identity certificates
+- Resolving your public profile information
+- Authenticating with services
+
+**Transaction Keys** are used for:
+- Signing Bitcoin transactions
+- Managing UTXOs and payments
+- Protocol-specific operations
+
+This separation provides both security and privacy benefits.
+
+### Identity Resolution
+Your identity key serves as a unique identifier that can be used to discover:
+- Your chosen display name and profile information
+- Verification badges and trust indicators
+- Public certificates and credentials
+- Contact preferences and communication methods
+
+Think of it like a decentralized phone book where your identity key is your number, but instead of just finding your phone number, people can discover rich identity information that you've chosen to make public.
+
+### Certificate-Based Trust
+Instead of trusting a central authority, decentralized identity relies on a web of cryptographic certificates. These certificates are like digital testimonials that others can independently verify:
+
+- **Self-Signed Certificates**: Claims you make about yourself
+- **Peer Certificates**: Verifications from other users
+- **Institutional Certificates**: Credentials from recognized organizations
+- **Service Certificates**: Verifications from specialized services
+
+## Trust and Verification Models
+
+### Web of Trust
+In a web of trust model, users verify each other's identities, creating networks of trusted relationships. This is similar to how you might trust a friend's recommendation about a restaurant - the more trusted connections someone has, the more credible they become.
+
+### Institutional Trust
+Some applications require higher assurance levels, so they rely on certificates from recognized institutions like universities, professional licensing boards, or government agencies. These certificates carry more weight because the issuers have established reputations and verification processes.
+
+### Hybrid Approaches
+Most real-world applications use a combination of trust models, adjusting requirements based on context. For example:
+- **Low-risk interactions** might accept self-signed certificates
+- **Financial transactions** might require institutional verification
+- **Professional networking** might emphasize peer verification within industry groups
+
+## Privacy and Selective Disclosure
+
+### Controlling Your Information
+One of the key benefits of decentralized identity is granular control over your personal information. You can:
+- Choose which attributes to make publicly discoverable
+- Reveal different information to different parties
+- Prove claims without revealing underlying data
+- Revoke access to previously shared information
+
+### Zero-Knowledge Proofs
+Advanced cryptographic techniques allow you to prove things about yourself without revealing the underlying information. For example, you could prove you're over 21 without revealing your exact age or birthdate.
+
+### Progressive Disclosure
+As trust builds between parties, you might choose to reveal more information. This allows relationships to develop naturally while maintaining privacy protection.
+
+## Identity Lifecycle
+
+### Getting Started
+Creating a decentralized identity involves:
+1. **Generating an identity key pair** (handled by your wallet)
+2. **Creating basic profile information** (name, avatar, contact preferences)
+3. **Obtaining initial certificates** to establish credibility
+4. **Making your identity discoverable** through resolution networks
+
+### Building Trust
+Over time, you accumulate certificates and verifications that build your reputation:
+- Verify your email address and social media accounts
+- Get endorsements from colleagues and friends
+- Obtain professional certifications and credentials
+- Participate in community verification programs
+
+### Maintaining Privacy
+As your identity grows, you maintain control by:
+- Regularly reviewing what information is public
+- Updating privacy preferences as needs change
+- Revoking outdated or unwanted certificates
+- Managing consent for data sharing
+
+## Real-World Applications
+
+### Passwordless Authentication
+Instead of remembering dozens of passwords, you can authenticate using your identity certificates. This is more secure than passwords and eliminates the need for password managers.
+
+### Professional Networking
+Verify professional credentials, work history, and skills through cryptographic certificates rather than relying on self-reported information on traditional platforms.
+
+### Age and Identity Verification
+Prove your age for restricted services without revealing your exact birthdate, or verify your identity for account creation without sharing unnecessary personal information.
+
+### Reputation Systems
+Build portable reputation that follows you across different platforms and applications, creating incentives for good behavior and reducing fraud.
+
+### Decentralized Social Networks
+Participate in social networks where your identity and connections are owned by you, not the platform, enabling true social media portability.
+
+## Benefits for Developers
+
+### Simplified User Onboarding
+Instead of building complex registration and verification systems, applications can rely on existing identity infrastructure and certificates.
+
+### Enhanced Security
+Cryptographic identity verification is more secure than traditional username/password systems and reduces the risk of account takeovers.
+
+### Regulatory Compliance
+Decentralized identity can help meet KYC (Know Your Customer) and AML (Anti-Money Laundering) requirements while preserving user privacy.
+
+### Interoperability
+Users can bring their identity and reputation from other applications, reducing friction and improving user experience.
+
+## Challenges and Considerations
+
+### User Experience
+Decentralized identity requires users to understand new concepts like key management and certificate verification. Good wallet software and user interfaces are essential for adoption.
+
+### Recovery and Backup
+Unlike centralized systems where you can reset your password, losing access to your identity keys can be permanent. Robust backup and recovery mechanisms are crucial.
+
+### Network Effects
+The value of decentralized identity increases as more people and organizations participate. Early adoption requires overcoming the "chicken and egg" problem.
+
+### Scalability
+As identity networks grow, efficient resolution and verification mechanisms become increasingly important to maintain performance.
+
+## The Future of Identity
+
+Decentralized identity represents a fundamental shift toward user sovereignty and privacy. As the technology matures and adoption grows, we can expect to see:
+
+- **Seamless Integration** with everyday applications and services
+- **Enhanced Privacy Protection** through advanced cryptographic techniques
+- **Global Interoperability** across different identity systems and networks
+- **Reduced Identity Fraud** through cryptographic verification
+- **New Business Models** that respect user privacy and data ownership
+
+By understanding these concepts, developers can build applications that respect user privacy, enhance security, and contribute to a more open and decentralized internet.
+
+## Related Concepts
+
+- [Identity Certificates](./identity-certificates.md) - How cryptographic certificates enable trust
+- [Digital Signatures](./signatures.md) - Cryptographic foundations of identity verification
+- [Trust Model](./trust-model.md) - Security assumptions in decentralized systems
+- [Key Management](./key-management.md) - Managing cryptographic keys securely
+
+## Further Reading
+
+- [Identity Management Tutorial](../tutorials/identity-management.md) - Hands-on implementation guide
+- [AuthFetch Tutorial](../tutorials/authfetch-tutorial.md) - Authenticated communication using identity
+- [Security Best Practices](../guides/security-best-practices.md) - Secure identity implementation patterns

package/docs/concepts/fees.md

@@ -0,0 +1,217 @@
+# Transaction Fees
+
+Understanding Bitcoin transaction fees and how they work in the BSV TypeScript SDK.
+
+## What are Transaction Fees?
+
+Transaction fees are payments to miners for including transactions in blocks:
+
+```typescript
+import { Transaction } from '@bsv/sdk'
+
+// Calculate transaction fee
+const tx = new Transaction()
+const feeRequired = tx.getFee()
+
+// Set custom fee rate
+const customFee = tx.getFee(feePerKB)
+```
+
+## Fee Calculation
+
+Fees are calculated based on transaction size:
+- **Fee Rate**: Satoshis per kilobyte (sat/kB)
+- **Transaction Size**: Total bytes in serialized transaction
+- **Total Fee**: Size × Fee Rate
+
+## SDK Fee Handling
+
+### Automatic Fee Calculation
+The SDK calculates fees automatically:
+```typescript
+// Wallet handles fees automatically
+const wallet = new WalletClient()
+const action = await wallet.createAction({
+  outputs: [{
+    satoshis: 1000,
+    lockingScript: script
+  }]
+})
+// Fee calculated and deducted automatically
+```
+
+### Manual Fee Control
+For advanced use cases:
+```typescript
+// Calculate fee manually
+const tx = new Transaction()
+tx.addInput(/* input */)
+tx.addOutput(/* output */)
+
+const estimatedSize = tx.getSerializedSize()
+const feeRequired = estimatedSize * feePerByte
+```
+
+## Fee Rates
+
+### Network Fee Rates
+BSV typically uses low, predictable fees:
+- **Standard Rate**: ~0.5 sat/byte
+- **Priority Rate**: ~1.0 sat/byte
+- **Economy Rate**: ~0.1 sat/byte
+
+### Dynamic Fee Estimation
+```typescript
+// Get current network fee rates
+const feeRates = await chainTracker.getFeeRates()
+const recommendedFee = feeRates.standard
+```
+
+## Fee Components
+
+### Input Costs
+Each input adds to transaction size:
+- Previous transaction hash (32 bytes)
+- Output index (4 bytes)
+- Unlocking script (variable)
+- Sequence number (4 bytes)
+
+### Output Costs
+Each output adds to transaction size:
+- Value (8 bytes)
+- Locking script length (1-9 bytes)
+- Locking script (variable)
+
+### Base Transaction
+Fixed overhead for every transaction:
+- Version (4 bytes)
+- Input count (1-9 bytes)
+- Output count (1-9 bytes)
+- Lock time (4 bytes)
+
+## Fee Optimization
+
+### UTXO Selection
+Choose UTXOs efficiently:
+```typescript
+// Prefer fewer, larger UTXOs to reduce fees
+const utxos = await wallet.getUTXOs()
+const selected = selectOptimalUTXOs(utxos, targetAmount)
+```
+
+### Output Consolidation
+Combine multiple payments:
+```typescript
+// Batch multiple outputs in one transaction
+const outputs = [
+  { satoshis: 1000, lockingScript: script1 },
+  { satoshis: 2000, lockingScript: script2 },
+  { satoshis: 1500, lockingScript: script3 }
+]
+```
+
+### Script Efficiency
+Use efficient script templates:
+```typescript
+// P2PKH is more efficient than complex scripts
+const p2pkh = new P2PKH()
+const efficientScript = p2pkh.lock(publicKeyHash)
+```
+
+## Fee Estimation
+
+### Size Estimation
+Estimate transaction size before creation:
+```typescript
+// Estimate size for fee calculation
+const estimatedInputs = 2
+const estimatedOutputs = 3
+const estimatedSize = estimateTransactionSize(estimatedInputs, estimatedOutputs)
+const estimatedFee = estimatedSize * feeRate
+```
+
+### Template-Based Estimation
+```typescript
+// Use script templates for accurate estimation
+const template = new P2PKH()
+const scriptSize = template.estimateLength([publicKeyHash])
+```
+
+## Error Handling
+
+Common fee-related issues:
+- Insufficient funds for fees
+- Fee rate too low for network
+- Transaction size miscalculation
+
+```typescript
+try {
+  const action = await wallet.createAction({
+    outputs: outputs
+  })
+} catch (error) {
+  if (error.message.includes('Insufficient funds')) {
+    // Handle insufficient balance for fees
+    console.log('Not enough funds to cover transaction and fees')
+  }
+}
+```
+
+## Best Practices
+
+### Fee Management
+- Always account for fees in balance calculations
+- Use appropriate fee rates for urgency
+- Monitor network conditions for fee adjustments
+- Implement fee estimation before transaction creation
+
+### Cost Optimization
+- Batch transactions when possible
+- Use efficient script templates
+- Optimize UTXO selection
+- Consider transaction timing
+
+### User Experience
+- Display estimated fees to users
+- Provide fee rate options (economy, standard, priority)
+- Handle insufficient fund errors gracefully
+- Show fee breakdown for transparency
+
+## Wallet Integration
+
+Most applications rely on wallets for fee handling:
+```typescript
+// Wallet manages fees automatically
+const wallet = new WalletClient()
+
+// Fees are calculated and deducted automatically
+const result = await wallet.createAction({
+  description: 'Payment with automatic fees',
+  outputs: [/* outputs */]
+})
+```
+
+## Advanced Fee Strategies
+
+### Replace-by-Fee (RBF)
+Increase fees for faster confirmation:
+```typescript
+// Create transaction with RBF enabled
+const tx = new Transaction()
+tx.setRBF(true) // Enable replace-by-fee
+```
+
+### Child-Pays-for-Parent (CPFP)
+Use dependent transactions to increase effective fee rate:
+```typescript
+// Create child transaction with higher fee
+const childTx = new Transaction()
+childTx.addInput(/* from parent transaction */)
+// Higher fee rate pulls parent transaction along
+```
+
+## Next Steps
+
+- Understand [Transaction Structure](./transaction-structure.md) for size calculation
+- Learn about [Wallet Integration](./wallet-integration.md) for automatic fee handling
+- Explore [Script Templates](./script-templates.md) for efficient fee optimization