@bsv/sdk 1.9.2 → 1.9.4

package/docs/concepts/key-management.md

@@ -1,185 +0,0 @@
-# Key Management
-
-Understanding how private keys, public keys, and cryptographic operations work in the BSV TypeScript SDK.
-
-## Cryptographic Keys
-
-Bitcoin uses elliptic curve cryptography (secp256k1) for key management:
-
-```typescript
-import { PrivateKey, PublicKey } from '@bsv/sdk'
-
-// Generate a new private key
-const privateKey = PrivateKey.fromRandom()
-
-// Derive the corresponding public key
-const publicKey = privateKey.toPublicKey()
-```
-
-## Private Keys
-
-Private keys are 256-bit numbers that control Bitcoin funds:
-
-### Generation
-
-```typescript
-// Secure random generation
-const privKey = PrivateKey.fromRandom()
-
-// From existing data (use carefully)
-const privKey2 = PrivateKey.fromString('hex_string')
-```
-
-### Formats
-
-```typescript
-// WIF (Wallet Import Format)
-const wif = privateKey.toWif()
-
-// Hex string
-const hex = privateKey.toString()
-
-// DER encoding
-const der = privateKey.toDER()
-```
-
-## Public Keys
-
-Public keys are derived from private keys and can be shared safely:
-
-### Derivation
-
-```typescript
-// Always derive from private key
-const publicKey = privateKey.toPublicKey()
-
-// Cannot go backwards (public -> private)
-```
-
-### Formats
-
-```typescript
-// Compressed (33 bytes) - preferred
-const compressed = publicKey.toString()
-
-// Uncompressed (65 bytes) - legacy
-const uncompressed = publicKey.toString(false)
-
-// DER encoding
-const der = publicKey.toDER()
-```
-
-## Digital Signatures
-
-Private keys create signatures that prove ownership:
-
-```typescript
-// Sign a message
-const message = 'Hello Bitcoin'
-const signature = privateKey.sign(message)
-
-// Verify with public key
-const isValid = publicKey.verify(message, signature)
-```
-
-## Key Derivation
-
-The SDK supports hierarchical key derivation:
-
-```typescript
-// Derive child keys (simplified example)
-const childKey = privateKey.deriveChild(0)
-const childPubKey = childKey.toPublicKey()
-```
-
-## Security Considerations
-
-### Private Key Security
-
-- **Never expose**: Private keys should never be logged or transmitted
-- **Secure storage**: Use encrypted storage for private keys
-- **Random generation**: Always use cryptographically secure randomness
-- **Access control**: Limit who can access private key operations
-
-### Best Practices
-
-```typescript
-// Good: Generate securely
-const key = PrivateKey.fromRandom()
-
-// Bad: Predictable generation
-const badKey = PrivateKey.fromString('1234567890abcdef...')
-
-// Good: Derive public key when needed
-const pubKey = key.toPublicKey()
-
-// Bad: Store private key unnecessarily
-localStorage.setItem('privateKey', key.toString())
-```
-
-## Wallet Integration
-
-In most applications, wallets handle key management:
-
-The `WalletClient` provides high-level key management through wallet integration:
-
-```typescript
-// Wallet manages keys securely
-const wallet = new WalletClient()
-
-// Application doesn't see private keys
-const action = await wallet.createAction({
-  outputs: [/* transaction outputs */]
-})
-```
-
-When using the `WalletClient`, keys are managed by the connected wallet service:
-
-The `WalletClient` approach is recommended for production applications as it provides:
-
-## Key Recovery
-
-Keys can be recovered from various formats:
-
-```typescript
-// From WIF format
-const key1 = PrivateKey.fromWif(wifString)
-
-// From hex string
-const key2 = PrivateKey.fromString(hexString)
-
-// From DER encoding
-const key3 = PrivateKey.fromDER(derBytes)
-```
-
-## Cryptographic Operations
-
-The SDK provides secure implementations of:
-
-- **ECDSA**: Digital signature algorithm
-- **ECDH**: Key exchange protocol
-- **Hash Functions**: SHA-256, RIPEMD-160
-- **AES**: Symmetric encryption
-
-## Memory Management
-
-Sensitive key data should be cleared when no longer needed:
-
-- Use secure memory practices
-- Clear variables containing key data
-- Avoid keeping keys in memory longer than necessary
-
-## Testing and Development
-
-For development and testing:
-
-- Use testnet for experiments
-- Generate new keys for each test
-- Never use mainnet keys in test code
-- Implement proper key rotation
-
-## Next Steps
-
-- Understand [Digital Signatures](./signatures.md) in detail
-- Learn about [Trust Model](./trust-model.md) considerations
-- Explore [Wallet Integration](./wallet-integration.md) patterns

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