@bsv/sdk 1.9.3 → 1.9.4

package/docs/concepts/script-templates.md

@@ -1,176 +0,0 @@
-# Script Templates
-
-Standard and custom Bitcoin script patterns available in the BSV TypeScript SDK.
-
-## What are Script Templates?
-
-Script templates provide reusable patterns for Bitcoin transaction locking and unlocking scripts:
-
-```typescript
-import { P2PKH } from '@bsv/sdk'
-
-// Use a standard template
-const template = new P2PKH()
-
-// Create locking script
-const lockingScript = template.lock(publicKeyHash)
-
-// Create unlocking script
-const unlockingScript = template.unlock(privateKey, signature)
-```
-
-## Standard Templates
-
-### P2PKH (Pay to Public Key Hash)
-
-The most common Bitcoin script pattern:
-
-```typescript
-const p2pkh = new P2PKH()
-const lock = p2pkh.lock(publicKeyHash)
-const unlock = p2pkh.unlock(privateKey, signature)
-```
-
-### P2PK (Pay to Public Key)
-
-Direct payment to a public key:
-
-```typescript
-const p2pk = new P2PK()
-const lock = p2pk.lock(publicKey)
-const unlock = p2pk.unlock(signature)
-```
-
-### OP_RETURN (Data Storage)
-
-Store arbitrary data on-chain:
-
-```typescript
-const opReturn = new OpReturn()
-const lock = opReturn.lock(data)
-// No unlock needed - unspendable output
-```
-
-## Custom Templates
-
-Create your own script templates:
-
-```typescript
-class TimeLockTemplate implements ScriptTemplate {
-  lock(lockTime: number, publicKeyHash: string): Script {
-    return new Script()
-      .writeNumber(lockTime)
-      .writeOpCode(OpCode.OP_CHECKLOCKTIMEVERIFY)
-      .writeOpCode(OpCode.OP_DROP)
-      .writeOpCode(OpCode.OP_DUP)
-      .writeOpCode(OpCode.OP_HASH160)
-      .writeBin(publicKeyHash)
-      .writeOpCode(OpCode.OP_EQUALVERIFY)
-      .writeOpCode(OpCode.OP_CHECKSIG)
-  }
-
-  unlock(signature: string, publicKey: string): Script {
-    return new Script()
-      .writeBin(signature)
-      .writeBin(publicKey)
-  }
-}
-```
-
-## Template Interface
-
-All templates implement the ScriptTemplate interface:
-
-```typescript
-interface ScriptTemplate {
-  lock(...args: any[]): Script
-  unlock(...args: any[]): Script
-  estimateLength?(args: any[]): number
-}
-```
-
-## Benefits
-
-### Reusability
-
-- Standard patterns for common use cases
-- Consistent implementation across applications
-- Reduced development time
-
-### Security
-
-- Well-tested script patterns
-- Reduced risk of script errors
-- Best practice implementations
-
-### Maintainability
-
-- Clear separation of script logic
-- Easy to update and modify
-- Testable components
-
-## Working with Templates
-
-### Transaction Integration
-
-```typescript
-// Use template in transaction
-const output = {
-  satoshis: 1000,
-  lockingScript: template.lock(publicKeyHash)
-}
-
-const input = {
-  sourceTransaction: prevTx,
-  sourceOutputIndex: 0,
-  unlockingScript: template.unlock(privateKey, signature)
-}
-```
-
-### Fee Estimation
-
-```typescript
-// Estimate script size for fee calculation
-const estimatedSize = template.estimateLength([publicKeyHash])
-const fee = estimatedSize * feePerByte
-```
-
-## Advanced Patterns
-
-### Multi-Signature
-
-```typescript
-class MultiSigTemplate implements ScriptTemplate {
-  lock(threshold: number, publicKeys: string[]): Script {
-    // Implementation for m-of-n multisig
-  }
-  
-  unlock(signatures: string[]): Script {
-    // Implementation for signature collection
-  }
-}
-```
-
-### Conditional Scripts
-
-```typescript
-class ConditionalTemplate implements ScriptTemplate {
-  lock(condition: Script, trueScript: Script, falseScript: Script): Script {
-    // Implementation for IF/ELSE logic
-  }
-}
-```
-
-## Best Practices
-
-- Use standard templates when possible
-- Test custom templates thoroughly
-- Document template parameters clearly
-- Consider script size and complexity
-- Validate inputs before script creation
-
-## Next Steps
-
-- Learn about [Digital Signatures](./signatures.md) for script authorization
-- Understand [Transaction Structure](./transaction-structure.md) integration
-- Explore [Key Management](./key-management.md) for script security

package/docs/concepts/sdk-philosophy.md

@@ -1,80 +0,0 @@
-# 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

@@ -1,194 +0,0 @@
-# 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

@@ -1,118 +0,0 @@
-# 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