@bsv/sdk 1.6.12 → 1.6.15

package/docs/concepts/spv-verification.md

@@ -5,6 +5,7 @@ Understanding Simplified Payment Verification and how it enables lightweight Bit
 ## 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
@@ -13,14 +14,18 @@ SPV allows verification of Bitcoin transactions without downloading the entire b
 ## 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'
 
@@ -30,7 +35,9 @@ const isValid = proof.verify(txid, merkleRoot)
 ```
 
 ### 3. Transaction Verification
+
 Combine proofs with block headers for full verification:
+
 ```typescript
 import { Transaction } from '@bsv/sdk'
 
@@ -45,6 +52,7 @@ const isValid = await Transaction.verify(
 ## 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
@@ -53,6 +61,7 @@ Bitcoin uses merkle trees to efficiently prove transaction 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
@@ -61,12 +70,14 @@ SPV provides strong security guarantees:
 ## 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
@@ -95,6 +106,7 @@ const result = await transaction.verify(chainTracker, {
 ## 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

package/docs/concepts/transaction-encoding.md

@@ -7,7 +7,9 @@ How Bitcoin transactions are serialized and deserialized in different formats wi
 The SDK supports multiple transaction encoding formats:
 
 ### Raw Transaction Format
+
 Standard Bitcoin transaction serialization:
+
 ```typescript
 import { Transaction } from '@bsv/sdk'
 
@@ -19,7 +21,9 @@ const tx = Transaction.fromHex(txHex)
 ```
 
 ### BEEF Format
+
 Bitcoin Extras Extension Format for efficient data exchange:
+
 ```typescript
 // Serialize to BEEF
 const beefHex = transaction.toBEEF()
@@ -29,7 +33,9 @@ const tx = Transaction.fromHexBEEF(beefHex)
 ```
 
 ### Binary Format
+
 Raw binary data for maximum efficiency:
+
 ```typescript
 // Serialize to binary
 const txBinary = transaction.toBinary()
@@ -41,6 +47,7 @@ const tx = Transaction.fromBinary(txBinary)
 ## Serialization Structure
 
 ### Standard Transaction
+
 ```
 Version (4 bytes)
 Input Count (varint)
@@ -51,6 +58,7 @@ Lock Time (4 bytes)
 ```
 
 ### Input Structure
+
 ```
 Previous TX Hash (32 bytes)
 Output Index (4 bytes)
@@ -60,6 +68,7 @@ Sequence (4 bytes)
 ```
 
 ### Output Structure
+
 ```
 Value (8 bytes)
 Script Length (varint)
@@ -69,6 +78,7 @@ Locking Script (variable)
 ## BEEF Enhancements
 
 BEEF format adds:
+
 - **Merkle Proofs**: SPV verification data
 - **Block Headers**: Chain validation information
 - **Metadata**: Additional transaction context
@@ -77,16 +87,19 @@ BEEF format adds:
 ## 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
@@ -94,6 +107,7 @@ BEEF format adds:
 ## Working with Encodings
 
 ### Conversion Between Formats
+
 ```typescript
 // Start with a transaction
 const tx = new Transaction()
@@ -107,6 +121,7 @@ const beef = tx.toBEEF()
 ```
 
 ### Validation
+
 ```typescript
 // Verify encoding integrity
 const originalTx = Transaction.fromHex(hex)
@@ -117,16 +132,19 @@ 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
@@ -134,6 +152,7 @@ console.log(hex === roundTripHex) // true
 ## Error Handling
 
 Common encoding issues:
+
 - Invalid hex characters
 - Truncated binary data
 - Malformed BEEF structures

package/docs/concepts/transaction-structure.md

@@ -34,22 +34,26 @@ tx.addOutput({
 ## 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

package/docs/concepts/trust-model.md

@@ -7,11 +7,13 @@ Understanding the security assumptions and trust relationships in BSV TypeScript
 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
@@ -19,19 +21,25 @@ The SDK is designed around minimizing trust requirements:
 ## 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
@@ -39,12 +47,14 @@ Optional trust relationships:
 ## 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
@@ -53,6 +63,7 @@ Optional trust relationships:
 ## Risk Mitigation
 
 ### Key Management
+
 ```typescript
 // Minimize private key exposure
 const wallet = new WalletClient() // Keys stay in wallet
@@ -62,6 +73,7 @@ const wallet = new WalletClient() // Keys stay in wallet
 ```
 
 ### Transaction Verification
+
 ```typescript
 // Always verify important transactions
 const isValid = await transaction.verify(chainTracker, {
@@ -71,6 +83,7 @@ const isValid = await transaction.verify(chainTracker, {
 ```
 
 ### Multiple Sources
+
 ```typescript
 // Use multiple chain trackers
 const config = {
@@ -84,6 +97,7 @@ const config = {
 ## 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
@@ -93,6 +107,7 @@ const config = {
 ## Application Design
 
 ### Security-First Design
+
 ```typescript
 // Validate all inputs
 function processTransaction(txHex: string) {
@@ -106,6 +121,7 @@ function processTransaction(txHex: string) {
 ```
 
 ### Error Handling
+
 ```typescript
 // Handle trust failures gracefully
 try {

package/docs/concepts/verification.md

@@ -19,21 +19,27 @@ const isValid = await transaction.verify(chainTracker, {
 ## 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
@@ -42,7 +48,9 @@ Confirm transaction inclusion in the blockchain:
 ## SDK Verification Methods
 
 ### Transaction.verify()
+
 Complete transaction verification:
+
 ```typescript
 const result = await transaction.verify(chainTracker, {
   merkleProof: merkleProof,
@@ -52,7 +60,9 @@ const result = await transaction.verify(chainTracker, {
 ```
 
 ### Script Verification
+
 Verify individual scripts:
+
 ```typescript
 const isValid = unlockingScript.verify(
   lockingScript,
@@ -62,7 +72,9 @@ const isValid = unlockingScript.verify(
 ```
 
 ### Signature Verification
+
 Check digital signatures:
+
 ```typescript
 const publicKey = PrivateKey.fromWif(wif).toPublicKey()
 const isValid = publicKey.verify(messageHash, signature)
@@ -71,7 +83,9 @@ const isValid = publicKey.verify(messageHash, signature)
 ## Verification Options
 
 ### Memory Limits
+
 Control script execution memory usage:
+
 ```typescript
 const options = {
   maxMemoryLimit: 50000000 // 50MB limit
@@ -79,7 +93,9 @@ const options = {
 ```
 
 ### Scripts-Only Mode
+
 Skip SPV verification for performance:
+
 ```typescript
 const options = {
   scriptsOnly: true
@@ -87,7 +103,9 @@ const options = {
 ```
 
 ### Custom Chain Tracker
+
 Use specific data sources:
+
 ```typescript
 const customTracker = new WhatsOnChain('testnet')
 const isValid = await transaction.verify(customTracker)
@@ -96,6 +114,7 @@ const isValid = await transaction.verify(customTracker)
 ## BEEF Verification
 
 BEEF format includes verification data:
+
 ```typescript
 // BEEF transactions include proofs
 const beefTx = Transaction.fromHexBEEF(beefData)
@@ -107,6 +126,7 @@ const isValid = await beefTx.verify(chainTracker)
 ## Error Handling
 
 Common verification failures:
+
 - Invalid signatures
 - Script execution errors
 - Missing merkle proofs
@@ -126,7 +146,9 @@ try {
 ## Performance Considerations
 
 ### Batch Verification
+
 Verify multiple transactions efficiently:
+
 ```typescript
 const results = await Promise.all(
   transactions.map(tx => tx.verify(chainTracker))
@@ -134,7 +156,9 @@ const results = await Promise.all(
 ```
 
 ### Caching
+
 Cache verification results:
+
 ```typescript
 const verificationCache = new Map()
 
@@ -147,16 +171,19 @@ if (!verificationCache.has(txid)) {
 ## 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
@@ -164,6 +191,7 @@ if (!verificationCache.has(txid)) {
 ## Common Use Cases
 
 ### Payment Verification
+
 ```typescript
 // Verify received payment
 const payment = Transaction.fromHex(paymentHex)
@@ -175,6 +203,7 @@ if (isValid) {
 ```
 
 ### Historical Transaction Audit
+
 ```typescript
 // Verify old transactions
 for (const txHex of historicalTransactions) {
@@ -187,6 +216,7 @@ for (const txHex of historicalTransactions) {
 ## Integration Patterns
 
 ### Wallet Integration
+
 ```typescript
 // Wallets typically handle verification
 const wallet = new WalletClient()
@@ -197,6 +227,7 @@ const action = await wallet.createAction({
 ```
 
 ### Application Verification
+
 ```typescript
 // Applications verify received transactions
 async function processIncomingTransaction(txHex: string) {

package/docs/concepts/wallet-integration.md

@@ -19,6 +19,7 @@ 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
@@ -51,16 +52,19 @@ const action = await wallet.createAction({
 ## 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
@@ -68,6 +72,7 @@ const action = await wallet.createAction({
 ## 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
@@ -76,6 +81,7 @@ The SDK works with various wallet implementations:
 ## Error Handling
 
 Common wallet integration scenarios:
+
 - Wallet not available or offline
 - User denies transaction approval
 - Insufficient funds in wallet