@bsv/sdk 1.9.3 → 1.9.4

package/docs/concepts/transaction-encoding.md

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

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

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

package/docs/concepts/verification.md

@@ -1,250 +0,0 @@
-# Transaction Verification
-
-Understanding how to verify Bitcoin transactions using the BSV TypeScript SDK.
-
-## What is Transaction Verification?
-
-Transaction verification ensures that Bitcoin transactions are valid and can be trusted:
-
-```typescript
-import { Transaction } from '@bsv/sdk'
-
-// Verify a transaction
-const isValid = await transaction.verify(chainTracker, {
-  merkleProof: proof,
-  blockHeader: header
-})
-```
-
-## Verification Levels
-
-### Basic Validation
-
-Check transaction structure and format:
-
-- Valid input/output formats
-- Correct serialization
-- Proper script syntax
-- Signature format validation
-
-### Script Execution
-
-Verify that unlocking scripts satisfy locking scripts:
-
-- Execute Bitcoin script opcodes
-- Validate signature operations
-- Check script conditions
-- Ensure proper stack state
-
-### SPV Verification
-
-Confirm transaction inclusion in the blockchain:
-
-- Verify merkle proofs
-- Validate block headers
-- Check proof of work
-- Confirm transaction position
-
-## SDK Verification Methods
-
-### Transaction.verify()
-
-Complete transaction verification:
-
-```typescript
-const result = await transaction.verify(chainTracker, {
-  merkleProof: merkleProof,
-  blockHeader: blockHeader,
-  maxMemoryLimit: 100000000
-})
-```
-
-### Script Verification
-
-Verify individual scripts:
-
-```typescript
-const isValid = unlockingScript.verify(
-  lockingScript,
-  transaction,
-  inputIndex
-)
-```
-
-### Signature Verification
-
-Check digital signatures:
-
-```typescript
-const publicKey = PrivateKey.fromWif(wif).toPublicKey()
-const isValid = publicKey.verify(messageHash, signature)
-```
-
-## Verification Options
-
-### Memory Limits
-
-Control script execution memory usage:
-
-```typescript
-const options = {
-  maxMemoryLimit: 50000000 // 50MB limit
-}
-```
-
-### Scripts-Only Mode
-
-Skip SPV verification for performance:
-
-```typescript
-const options = {
-  scriptsOnly: true
-}
-```
-
-### Custom Chain Tracker
-
-Use specific data sources:
-
-```typescript
-const customTracker = new WhatsOnChain('testnet')
-const isValid = await transaction.verify(customTracker)
-```
-
-## BEEF Verification
-
-BEEF format includes verification data:
-
-```typescript
-// BEEF transactions include proofs
-const beefTx = Transaction.fromHexBEEF(beefData)
-
-// Verify using included proofs
-const isValid = await beefTx.verify(chainTracker)
-```
-
-## Error Handling
-
-Common verification failures:
-
-- Invalid signatures
-- Script execution errors
-- Missing merkle proofs
-- Network connectivity issues
-
-```typescript
-try {
-  const isValid = await transaction.verify(chainTracker)
-  if (!isValid) {
-    console.log('Transaction verification failed')
-  }
-} catch (error) {
-  console.error('Verification error:', error.message)
-}
-```
-
-## Performance Considerations
-
-### Batch Verification
-
-Verify multiple transactions efficiently:
-
-```typescript
-const results = await Promise.all(
-  transactions.map(tx => tx.verify(chainTracker))
-)
-```
-
-### Caching
-
-Cache verification results:
-
-```typescript
-const verificationCache = new Map()
-
-if (!verificationCache.has(txid)) {
-  const result = await transaction.verify(chainTracker)
-  verificationCache.set(txid, result)
-}
-```
-
-## Security Best Practices
-
-### Always Verify
-
-- Verify transactions before trusting them
-- Check both script execution and SPV proofs
-- Validate input data before verification
-
-### Multiple Sources
-
-- Use multiple chain trackers for redundancy
-- Cross-check verification results
-- Implement fallback mechanisms
-
-### Resource Limits
-
-- Set appropriate memory limits
-- Timeout long-running verifications
-- Monitor verification performance
-
-## Common Use Cases
-
-### Payment Verification
-
-```typescript
-// Verify received payment
-const payment = Transaction.fromHex(paymentHex)
-const isValid = await payment.verify(chainTracker)
-
-if (isValid) {
-  // Process confirmed payment
-}
-```
-
-### Historical Transaction Audit
-
-```typescript
-// Verify old transactions
-for (const txHex of historicalTransactions) {
-  const tx = Transaction.fromHex(txHex)
-  const result = await tx.verify(chainTracker)
-  console.log(`Transaction ${tx.id()}: ${result ? 'Valid' : 'Invalid'}`)
-}
-```
-
-## Integration Patterns
-
-### Wallet Integration
-
-```typescript
-// Wallets typically handle verification
-const wallet = new WalletClient()
-const action = await wallet.createAction({
-  outputs: [/* outputs */]
-})
-// Wallet verifies before broadcasting
-```
-
-### Application Verification
-
-```typescript
-// Applications verify received transactions
-async function processIncomingTransaction(txHex: string) {
-  const tx = Transaction.fromHex(txHex)
-  
-  if (await tx.verify(chainTracker)) {
-    // Process verified transaction
-    await handleValidTransaction(tx)
-  } else {
-    // Reject invalid transaction
-    throw new Error('Invalid transaction received')
-  }
-}
-```
-
-## Next Steps
-
-- Learn about [SPV Verification](./spv-verification.md) concepts
-- Understand [Digital Signatures](./signatures.md) validation
-- Explore [BEEF Format](./beef.md) for efficient verification

package/docs/concepts/wallet-integration.md

@@ -1,101 +0,0 @@
-# Wallet Integration
-
-How the BSV TypeScript SDK connects with Bitcoin wallets and manages user authentication.
-
-## Wallet Connection Model
-
-The SDK uses a standardized approach to connect with Bitcoin wallets:
-
-```typescript
-import { WalletClient } from '@bsv/sdk'
-
-// Connect to a wallet
-const wallet = new WalletClient('https://wallet-url')
-
-// Authenticate with the wallet
-await wallet.authenticate()
-```
-
-## BRC-100 Compliance
-
-The SDK follows the BRC-100 standard for wallet communication:
-
-- **Standardized APIs**: Consistent interface across different wallets
-- **Authentication**: Secure identity verification
-- **Transaction Signing**: Wallet handles private key operations
-- **UTXO Management**: Wallet manages available funds
-
-## Authentication Flow
-
-1. **Connection**: Establish connection to wallet service
-2. **Identity**: Wallet provides user identity information
-3. **Capabilities**: Discover what the wallet can do
-4. **Authorization**: User grants permission for specific operations
-
-## Transaction Creation
-
-The wallet handles sensitive operations:
-
-```typescript
-// Create a transaction action
-const action = await wallet.createAction({
-  description: 'Payment transaction',
-  outputs: [{
-    satoshis: 1000,
-    lockingScript: recipientScript
-  }]
-})
-
-// Wallet signs and broadcasts automatically
-```
-
-## Key Benefits
-
-### Security
-
-- Private keys never leave the wallet
-- User controls transaction approval
-- Secure authentication protocols
-
-### User Experience
-
-- Familiar wallet interface
-- Consistent across applications
-- Single sign-on capabilities
-
-### Developer Simplicity
-
-- No key management complexity
-- Standardized APIs
-- Automatic UTXO handling
-
-## Wallet Types
-
-The SDK works with various wallet implementations:
-
-- **Desktop Wallets**: Local applications with full control
-- **Web Wallets**: Browser-based wallet services
-- **Mobile Wallets**: Smartphone applications
-- **Hardware Wallets**: Secure hardware devices
-
-## Error Handling
-
-Common wallet integration scenarios:
-
-- Wallet not available or offline
-- User denies transaction approval
-- Insufficient funds in wallet
-- Network connectivity issues
-
-## Best Practices
-
-- Always handle wallet connection failures gracefully
-- Provide clear transaction descriptions to users
-- Implement retry logic for network issues
-- Cache wallet capabilities to improve performance
-
-## Next Steps
-
-- Learn about [Chain Tracking](./chain-tracking.md) for network data
-- Understand [Key Management](./key-management.md) concepts
-- Explore [Trust Model](./trust-model.md) considerations