@bsv/sdk 1.9.2 → 1.9.4

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

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