@bsv/sdk 1.6.9 → 1.6.11

package/docs/concepts/sdk-philosophy.md

@@ -0,0 +1,72 @@
+# SDK Design Philosophy
+
+This document details the core principles behind the BSV TypeScript SDK architecture and design decisions.
+
+## Zero Dependencies
+
+The SDK is built without external dependencies to:
+- Minimize security attack surface
+- Reduce bundle size and complexity
+- Ensure long-term stability
+- Provide predictable behavior
+
+## SPV-First Approach
+
+The SDK prioritizes Simplified Payment Verification:
+- **Lightweight**: No need to download the full blockchain
+- **Efficient**: Verify transactions using merkle proofs
+- **Scalable**: Works with millions of transactions
+- **Secure**: Cryptographically verifiable without full nodes
+
+## Vendor Neutrality
+
+The SDK works with any compliant Bitcoin infrastructure:
+- **Wallet Agnostic**: Supports any BRC-100 compliant wallet
+- **Network Flexible**: Works with different chain tracking services
+- **Service Independent**: No lock-in to specific providers
+
+## Modular Design
+
+Components are designed to work independently:
+- **Composable**: Mix and match functionality as needed
+- **Extensible**: Easy to add custom implementations
+- **Testable**: Each component can be tested in isolation
+- **Maintainable**: Clear separation of concerns
+
+## TypeScript-First
+
+Built specifically for TypeScript to provide:
+- **Type Safety**: Catch errors at compile time
+- **Developer Experience**: Rich IDE support and autocomplete
+- **Documentation**: Types serve as living documentation
+- **Reliability**: Reduced runtime errors
+
+## Security by Design
+
+Security considerations are built into every component:
+- **Cryptographic Primitives**: Secure implementations of Bitcoin cryptography
+- **Input Validation**: All inputs are validated and sanitized
+- **Error Handling**: Comprehensive error handling prevents information leakage
+- **Best Practices**: Follows established security patterns
+
+## Performance Focused
+
+Optimized for real-world application needs:
+- **Memory Efficient**: Minimal memory footprint
+- **Fast Execution**: Optimized critical paths
+- **Batch Processing**: Support for high-throughput scenarios
+- **Caching**: Intelligent caching where appropriate
+
+## Developer-Friendly
+
+Designed to make Bitcoin development accessible:
+- **Clear APIs**: Intuitive method names and parameters
+- **Comprehensive Documentation**: Tutorials, guides, and references
+- **Working Examples**: Real code that developers can use immediately
+- **Progressive Complexity**: Start simple, add complexity as needed
+
+## Next Steps
+
+- Understand [Wallet Integration](./wallet-integration.md) patterns
+- Learn about [SPV Verification](./spv-verification.md) concepts
+- Explore [Key Management](./key-management.md) approaches

package/docs/concepts/signatures.md

@@ -0,0 +1,179 @@
+# Digital Signatures
+
+How digital signatures work in Bitcoin and their implementation in the BSV TypeScript SDK.
+
+## What are Digital Signatures?
+
+Digital signatures prove ownership and authorize Bitcoin transactions:
+
+```typescript
+import { PrivateKey, Transaction } from '@bsv/sdk'
+
+// Create a signature
+const privateKey = PrivateKey.fromRandom()
+const message = 'transaction data'
+const signature = privateKey.sign(message)
+
+// Verify the signature
+const publicKey = privateKey.toPublicKey()
+const isValid = publicKey.verify(message, signature)
+```
+
+## Bitcoin Signatures
+
+Bitcoin uses ECDSA (Elliptic Curve Digital Signature Algorithm):
+- **secp256k1**: The elliptic curve used by Bitcoin
+- **SHA-256**: Hash function for message digests
+- **DER Encoding**: Standard format for signature serialization
+
+## SIGHASH Types
+
+SIGHASH flags determine what parts of a transaction are signed:
+
+### SIGHASH_ALL (Default)
+Signs all inputs and outputs:
+```typescript
+const signature = privateKey.sign(txHash, 'all')
+```
+
+### SIGHASH_NONE
+Signs all inputs but no outputs:
+```typescript
+const signature = privateKey.sign(txHash, 'none')
+```
+
+### SIGHASH_SINGLE
+Signs all inputs and one corresponding output:
+```typescript
+const signature = privateKey.sign(txHash, 'single')
+```
+
+### SIGHASH_ANYONECANPAY
+Can be combined with other flags to sign only one input:
+```typescript
+const signature = privateKey.sign(txHash, 'all|anyonecanpay')
+```
+
+## Transaction Signing
+
+The SDK handles transaction signing automatically:
+
+```typescript
+// Manual signing (low-level)
+const tx = new Transaction()
+const signature = tx.sign(privateKey, inputIndex, sighashType)
+
+// Wallet signing (recommended)
+const wallet = new WalletClient()
+const action = await wallet.createAction({
+  outputs: [/* outputs */]
+})
+// Wallet handles signing internally
+```
+
+## Signature Verification
+
+Verify signatures to ensure transaction validity:
+
+```typescript
+// Verify a specific signature
+const isValid = publicKey.verify(messageHash, signature)
+
+// Verify entire transaction
+const txValid = await transaction.verify(chainTracker)
+```
+
+## DER Encoding
+
+Signatures are encoded in DER format:
+
+```typescript
+// Get DER-encoded signature
+const derSignature = signature.toDER()
+
+// Parse DER signature
+const sig = Signature.fromDER(derBytes)
+
+// Get r and s components
+const r = signature.r
+const s = signature.s
+```
+
+## Security Considerations
+
+### Nonce Security
+- Each signature must use a unique, random nonce
+- Reusing nonces can leak private keys
+- The SDK handles nonce generation securely
+
+### Signature Malleability
+- Bitcoin signatures can be modified without invalidating them
+- Use canonical signatures to prevent malleability
+- The SDK produces canonical signatures by default
+
+### Hash Types
+- Choose appropriate SIGHASH types for your use case
+- SIGHASH_ALL is safest for most applications
+- Other types enable advanced transaction patterns
+
+## Common Patterns
+
+### Multi-Input Signing
+```typescript
+// Sign multiple inputs in a transaction
+for (let i = 0; i < transaction.inputs.length; i++) {
+  const signature = privateKey.sign(transaction.getSignatureHash(i))
+  transaction.inputs[i].unlockingScript = createUnlockingScript(signature)
+}
+```
+
+### Conditional Signatures
+```typescript
+// Different signatures for different conditions
+const signature1 = privateKey1.sign(txHash, 'all')
+const signature2 = privateKey2.sign(txHash, 'single')
+```
+
+## Error Handling
+
+Common signature issues:
+- Invalid private key format
+- Incorrect message hash
+- Malformed signature data
+- Verification failures
+
+```typescript
+try {
+  const signature = privateKey.sign(message)
+} catch (error) {
+  console.error('Signing failed:', error.message)
+}
+```
+
+## Best Practices
+
+- Always use secure random number generation
+- Verify signatures before trusting them
+- Use appropriate SIGHASH types for your use case
+- Store signatures in DER format for interoperability
+- Never reuse nonces across signatures
+
+## Wallet Integration
+
+Most applications use wallets for signing:
+
+```typescript
+// Wallet handles signature creation
+const wallet = new WalletClient()
+const result = await wallet.createAction({
+  description: 'Payment transaction',
+  outputs: [/* outputs */]
+})
+// Signatures created automatically
+```
+
+## Next Steps
+
+- Understand [Key Management](./key-management.md) for signature security
+- Learn about [Script Templates](./script-templates.md) for signature usage
+- Explore [Transaction Structure](./transaction-structure.md) for signature placement

package/docs/concepts/spv-verification.md

@@ -0,0 +1,106 @@
+# SPV Verification
+
+Understanding Simplified Payment Verification and how it enables lightweight Bitcoin applications.
+
+## What is SPV?
+
+SPV allows verification of Bitcoin transactions without downloading the entire blockchain:
+- **Lightweight**: Only requires block headers and merkle proofs
+- **Secure**: Cryptographically verifiable using merkle trees
+- **Efficient**: Scales to millions of transactions
+- **Practical**: Enables mobile and web applications
+
+## How SPV Works
+
+### 1. Block Headers
+Download only block headers (80 bytes each) instead of full blocks:
+```typescript
+// Block header contains merkle root
+const header = await chainTracker.getBlockHeader(blockHash)
+```
+
+### 2. Merkle Proofs
+Verify transaction inclusion using merkle proofs:
+```typescript
+import { MerklePath } from '@bsv/sdk'
+
+// Verify transaction is in block
+const proof = MerklePath.fromHex(proofHex)
+const isValid = proof.verify(txid, merkleRoot)
+```
+
+### 3. Transaction Verification
+Combine proofs with block headers for full verification:
+```typescript
+import { Transaction } from '@bsv/sdk'
+
+// Verify transaction with SPV
+const isValid = await Transaction.verify(
+  transaction,
+  chainTracker,
+  { merkleProof: proof }
+)
+```
+
+## Merkle Trees
+
+Bitcoin uses merkle trees to efficiently prove transaction inclusion:
+- **Binary Tree**: Each leaf is a transaction ID
+- **Hash Pairs**: Parent nodes are hashes of child pairs
+- **Root Hash**: Single hash representing all transactions
+- **Proof Path**: Minimal data needed to verify inclusion
+
+## Security Model
+
+SPV provides strong security guarantees:
+- **Proof of Work**: Block headers contain proof of work
+- **Cryptographic Hashes**: Merkle proofs use SHA-256
+- **Chain Validation**: Verify header chain integrity
+- **Fraud Detection**: Invalid proofs are cryptographically detectable
+
+## Trade-offs
+
+### Advantages
+- **Low Resource Usage**: Minimal storage and bandwidth
+- **Fast Synchronization**: Quick startup time
+- **Scalability**: Works with any blockchain size
+- **Privacy**: No need to reveal which transactions you care about
+
+### Limitations
+- **Trust Assumptions**: Relies on honest majority of miners
+- **Network Dependency**: Requires connection to full nodes
+- **Delayed Detection**: May not immediately detect invalid blocks
+
+## SDK Implementation
+
+The SDK provides comprehensive SPV support:
+
+```typescript
+// Configure SPV verification
+const config = {
+  spv: {
+    enabled: true,
+    maxMemoryLimit: 100000000, // 100MB
+    chainTracker: chainTracker
+  }
+}
+
+// Verify transaction with SPV
+const result = await transaction.verify(chainTracker, {
+  merkleProof: proof,
+  blockHeader: header
+})
+```
+
+## BEEF Integration
+
+SPV works seamlessly with BEEF format:
+- **Efficient Encoding**: BEEF includes merkle proofs
+- **Batch Verification**: Verify multiple transactions together
+- **Standardized Format**: Consistent across applications
+
+## Next Steps
+
+- Learn about [BEEF Format](./beef.md) for efficient data exchange
+- Understand [Transaction Encoding](./transaction-encoding.md) formats
+- Explore [Trust Model](./trust-model.md) considerations

package/docs/concepts/transaction-encoding.md

@@ -0,0 +1,148 @@
+# Transaction Encoding
+
+How Bitcoin transactions are serialized and deserialized in different formats within the BSV TypeScript SDK.
+
+## Encoding Formats
+
+The SDK supports multiple transaction encoding formats:
+
+### Raw Transaction Format
+Standard Bitcoin transaction serialization:
+```typescript
+import { Transaction } from '@bsv/sdk'
+
+// Serialize to hex
+const txHex = transaction.toHex()
+
+// Deserialize from hex
+const tx = Transaction.fromHex(txHex)
+```
+
+### BEEF Format
+Bitcoin Extras Extension Format for efficient data exchange:
+```typescript
+// Serialize to BEEF
+const beefHex = transaction.toBEEF()
+
+// Deserialize from BEEF
+const tx = Transaction.fromHexBEEF(beefHex)
+```
+
+### Binary Format
+Raw binary data for maximum efficiency:
+```typescript
+// Serialize to binary
+const txBinary = transaction.toBinary()
+
+// Deserialize from binary
+const tx = Transaction.fromBinary(txBinary)
+```
+
+## Serialization Structure
+
+### Standard Transaction
+```
+Version (4 bytes)
+Input Count (varint)
+Inputs (variable)
+Output Count (varint)  
+Outputs (variable)
+Lock Time (4 bytes)
+```
+
+### Input Structure
+```
+Previous TX Hash (32 bytes)
+Output Index (4 bytes)
+Script Length (varint)
+Unlocking Script (variable)
+Sequence (4 bytes)
+```
+
+### Output Structure
+```
+Value (8 bytes)
+Script Length (varint)
+Locking Script (variable)
+```
+
+## BEEF Enhancements
+
+BEEF format adds:
+- **Merkle Proofs**: SPV verification data
+- **Block Headers**: Chain validation information
+- **Metadata**: Additional transaction context
+- **Compression**: Efficient encoding for large datasets
+
+## Encoding Considerations
+
+### Size Optimization
+- Use BEEF for transactions with proofs
+- Use raw format for minimal overhead
+- Consider compression for large batches
+
+### Compatibility
+- Raw format works with all Bitcoin software
+- BEEF requires compatible parsers
+- Binary format is most efficient but less portable
+
+### Performance
+- Binary operations are fastest
+- Hex encoding is human-readable
+- BEEF provides best feature/size ratio
+
+## Working with Encodings
+
+### Conversion Between Formats
+```typescript
+// Start with a transaction
+const tx = new Transaction()
+
+// Convert between formats
+const hex = tx.toHex()
+const binary = tx.toBinary()
+const beef = tx.toBEEF()
+
+// All represent the same transaction
+```
+
+### Validation
+```typescript
+// Verify encoding integrity
+const originalTx = Transaction.fromHex(hex)
+const roundTripHex = originalTx.toHex()
+console.log(hex === roundTripHex) // true
+```
+
+## Use Cases
+
+### Network Transmission
+- Use hex for JSON APIs
+- Use binary for efficient protocols
+- Use BEEF for SPV applications
+
+### Storage
+- Raw format for blockchain storage
+- BEEF for application databases
+- Binary for memory-constrained environments
+
+### Interoperability
+- Hex for debugging and logging
+- Raw format for wallet compatibility
+- BEEF for modern Bitcoin applications
+
+## Error Handling
+
+Common encoding issues:
+- Invalid hex characters
+- Truncated binary data
+- Malformed BEEF structures
+- Version compatibility problems
+
+The SDK provides comprehensive validation and error reporting.
+
+## Next Steps
+
+- Understand [BEEF Format](./beef.md) in detail
+- Learn about [SPV Verification](./spv-verification.md) with BEEF
+- Explore [Transaction Structure](./transaction-structure.md) fundamentals

package/docs/concepts/transaction-structure.md

@@ -0,0 +1,63 @@
+# Transaction Structure
+
+Understanding how Bitcoin transactions work and their representation in the BSV TypeScript SDK.
+
+## Basic Transaction Components
+
+A Bitcoin transaction consists of:
+
+- **Inputs**: References to previous transaction outputs being spent
+- **Outputs**: New transaction outputs being created
+- **Metadata**: Version, lock time, and other transaction properties
+
+## Transaction in the SDK
+
+```typescript
+import { Transaction } from '@bsv/sdk'
+
+// Create a new transaction
+const tx = new Transaction()
+
+// Add inputs and outputs
+tx.addInput({
+  sourceTransaction: previousTx,
+  sourceOutputIndex: 0,
+  unlockingScript: unlockingScript
+})
+
+tx.addOutput({
+  satoshis: 1000,
+  lockingScript: lockingScript
+})
+```
+
+## Key Concepts
+
+### Inputs
+- Reference previous transaction outputs (UTXOs)
+- Include unlocking scripts to prove ownership
+- Must be fully consumed (no partial spending)
+
+### Outputs
+- Create new UTXOs with specific values
+- Include locking scripts that define spending conditions
+- Can be spent by future transactions
+
+### Transaction ID
+- Unique identifier calculated from transaction data
+- Used to reference the transaction in inputs
+
+## Working with Transactions
+
+The SDK provides methods to:
+- Serialize transactions to hex format
+- Calculate transaction fees
+- Verify transaction validity
+- Sign transaction inputs
+
+## Next Steps
+
+- Learn about [BEEF Format](./beef.md) for efficient transaction representation with validation data
+- Learn about [Script Templates](./script-templates.md) for locking/unlocking scripts
+- Understand [Digital Signatures](./signatures.md) for transaction authorization
+- Explore [Transaction Encoding](./transaction-encoding.md) for serialization formats

package/docs/concepts/trust-model.md

@@ -0,0 +1,123 @@
+# Trust Model
+
+Understanding the security assumptions and trust relationships in BSV TypeScript SDK applications.
+
+## Core Trust Principles
+
+The SDK is designed around minimizing trust requirements:
+
+### Trustless Verification
+- **Cryptographic Proofs**: Verify transactions mathematically
+- **SPV Security**: Validate without trusting third parties
+- **Self-Sovereign**: Users control their own keys and data
+
+### Minimized Dependencies
+- **Zero External Dependencies**: Reduces attack surface
+- **Self-Contained**: All cryptographic operations built-in
+- **Auditable**: Open source and transparent implementation
+
+## Trust Relationships
+
+### User Trust
+Users must trust:
+- **The SDK Code**: Open source and auditable
+- **Their Wallet**: Manages private keys securely
+- **Their Device**: Secure execution environment
+
+### Network Trust
+Applications rely on:
+- **Bitcoin Network**: Honest majority of miners
+- **Chain Trackers**: Provide accurate blockchain data
+- **SPV Assumptions**: Valid merkle proofs and headers
+
+### Service Trust
+Optional trust relationships:
+- **Wallet Providers**: If using hosted wallets
+- **ARC Services**: For transaction broadcasting
+- **Overlay Services**: For additional functionality
+
+## Security Assumptions
+
+### Cryptographic Security
+- **secp256k1**: Elliptic curve is secure
+- **SHA-256**: Hash function is collision-resistant
+- **ECDSA**: Digital signature scheme is unforgeable
+- **Random Number Generation**: Entropy source is secure
+
+### Network Security
+- **Proof of Work**: Mining provides security
+- **Longest Chain**: Honest chain has most work
+- **Block Finality**: Deep confirmations prevent reorganization
+- **Network Connectivity**: Access to honest nodes
+
+## Risk Mitigation
+
+### Key Management
+```typescript
+// Minimize private key exposure
+const wallet = new WalletClient() // Keys stay in wallet
+
+// Avoid direct key handling
+// const privateKey = PrivateKey.fromString() // Higher risk
+```
+
+### Transaction Verification
+```typescript
+// Always verify important transactions
+const isValid = await transaction.verify(chainTracker, {
+  merkleProof: proof,
+  blockHeader: header
+})
+```
+
+### Multiple Sources
+```typescript
+// Use multiple chain trackers
+const config = {
+  chainTracker: {
+    primary: 'WhatsOnChain',
+    fallbacks: ['GorillaPool', 'TAAL']
+  }
+}
+```
+
+## Threat Model
+
+### Attacks to Consider
+- **Private Key Compromise**: Secure key storage
+- **Man-in-the-Middle**: Use HTTPS and verify certificates
+- **Service Downtime**: Implement fallback mechanisms
+- **Double Spending**: Wait for confirmations
+- **Replay Attacks**: Use unique transaction IDs
+
+## Application Design
+
+### Security-First Design
+```typescript
+// Validate all inputs
+function processTransaction(txHex: string) {
+  if (!isValidHex(txHex)) {
+    throw new Error('Invalid transaction hex')
+  }
+  
+  const tx = Transaction.fromHex(txHex)
+  // Process verified transaction
+}
+```
+
+### Error Handling
+```typescript
+// Handle trust failures gracefully
+try {
+  const result = await chainTracker.getTransaction(txid)
+} catch (error) {
+  // Fallback to alternative source
+  const backup = await fallbackTracker.getTransaction(txid)
+}
+```
+
+## Next Steps
+
+- Review [Key Management](./key-management.md) security practices
+- Understand [SPV Verification](./spv-verification.md) assumptions
+- Learn about [Wallet Integration](./wallet-integration.md) trust models