@bsv/sdk 1.9.2 → 1.9.4

package/docs/MARKDOWN_VALIDATION_GUIDE.md

@@ -1,175 +0,0 @@
-# Markdown Validation Guide for Teranode Documentation
-
-This guide provides comprehensive solutions to prevent and catch markdown formatting issues that cause problems in Material MkDocs rendering.
-
-## 🛠️ Available Validation Tools
-
-### 1. Pre-commit Hooks (Automatic)
-
-**Setup**: Already configured in `.pre-commit-config.yaml`
-
-- **markdownlint**: Catches formatting issues before commits
-- **Configuration**: `.markdownlint.yml` with rules tailored for Material MkDocs
-
-**Usage**:
-
-```bash
-# Install pre-commit hooks
-pre-commit install
-
-# Run manually on all files
-pre-commit run markdownlint --all-files
-```
-
-### 2. Custom Validation Script
-
-**Location**: `scripts/validate-markdown.py`
-
-**Features**:
-
-- Detects missing blank lines before lists
-- Finds inconsistent nested bullet indentation
-- Identifies configuration parameters missing Type/Default/Impact details
-- Can automatically fix issues with `--fix` flag
-
-**Usage**:
-
-```bash
-# Validate all documentation
-python3 scripts/validate-markdown.py docs/
-
-# Validate and auto-fix issues
-python3 scripts/validate-markdown.py docs/ --fix
-
-# Validate single file
-python3 scripts/validate-markdown.py docs/topics/services/alert.md
-```
-
-### 3. VS Code Extensions (Real-time)
-
-**Recommended Extensions**:
-
-- **markdownlint**: Real-time linting in editor
-- **Markdown All in One**: Preview and formatting
-- **Material Theme**: Better syntax highlighting
-
-**Setup**:
-
-1. Install extensions
-2. Add to VS Code settings.json:
-
-```json
-{
-  "markdownlint.config": {
-    "MD007": { "indent": 4 },
-    "MD032": true,
-    "MD013": false
-  }
-}
-```
-
-## 🎯 Common Issues & Prevention
-
-### Issue 1: Missing Blank Lines Before Lists
-
-**Problem**: Lists render inline instead of as proper lists
-**Solution**: Always add blank line before lists
-
-```markdown
-❌ Wrong:
-Configuration options:
-
-- Option 1
-- Option 2
-
-✅ Correct:
-Configuration options:
-
-- Option 1
-- Option 2
-```
-
-### Issue 2: Inconsistent Nested Indentation
-
-**Problem**: Nested items don't render as nested
-**Solution**: Use exactly 4 spaces for nested items
-
-```markdown
-❌ Wrong:
-
-- Main item
-  - Nested item (2 spaces)
-
-✅ Correct:
-
-- Main item
-    - Nested item (4 spaces)
-```
-
-### Issue 3: Configuration Parameter Formatting
-
-**Problem**: Inconsistent parameter documentation
-**Solution**: Use standard format for all parameters
-
-```markdown
-✅ Standard Format:
-1. **`parameter_name`**: Brief description.
-    - Type: string
-    - Default: "value"
-    - Impact: Detailed explanation of what this controls.
-```
-
-## 🚀 Workflow Integration
-
-### Daily Development
-
-1. **VS Code Extensions**: Real-time feedback while editing
-2. **Pre-commit Hooks**: Automatic validation before commits
-3. **Custom Script**: Bulk validation and fixes
-
-### CI/CD Pipeline
-
-1. **GitHub Actions**: Validate all PRs
-2. **Deployment**: Only deploy if validation passes
-
-### Periodic Maintenance
-
-```bash
-# Weekly validation run
-python3 scripts/validate-markdown.py docs/ --fix
-git add -A
-git commit -m "docs: fix markdown formatting issues"
-```
-
-## 📋 Validation Checklist
-
-Before committing documentation changes:
-
-- [ ] Run custom validation script
-- [ ] Check pre-commit hooks pass
-- [ ] Preview in Material MkDocs locally
-- [ ] Verify nested lists render correctly
-- [ ] Confirm configuration parameters follow standard format
-
-## 🔧 Quick Fixes
-
-**Fix all formatting issues in docs**:
-
-```bash
-python3 scripts/validate-markdown.py docs/ --fix
-```
-
-**Run markdownlint**:
-
-```bash
-markdownlint docs/ --config .markdownlint.yml --fix
-```
-
-**Preview locally**:
-
-```bash
-mkdocs serve
-# Open http://localhost:8000
-```
-
-This multi-layered approach ensures high-quality, consistently formatted documentation that renders perfectly in Material MkDocs.

package/docs/concepts/beef.md

@@ -1,92 +0,0 @@
-# BEEF Format
-
-Bitcoin Extras Extension Format (BEEF) - an efficient way to package Bitcoin transactions with their verification data.
-
-## What is BEEF?
-
-BEEF is a standardized format that combines:
-
-- **Transaction Data**: The actual Bitcoin transaction
-- **Merkle Proofs**: SPV verification data
-- **Block Headers**: Chain validation information
-- **Metadata**: Additional context and references
-
-## BEEF in the SDK
-
-```typescript
-import { Transaction } from '@bsv/sdk'
-
-// Create transaction with BEEF data
-const tx = Transaction.fromHexBEEF(beefHex)
-
-// Serialize transaction to BEEF
-const beefData = transaction.toBEEF()
-
-// Verify transaction using included proofs
-const isValid = await tx.verify(chainTracker)
-```
-
-## Key Benefits
-
-### Efficiency
-
-- **Compact**: Includes only necessary verification data
-- **Self-Contained**: No external lookups required
-- **Batch Processing**: Multiple transactions in one package
-
-### SPV Integration
-
-- **Merkle Proofs**: Verify transaction inclusion
-- **Block Headers**: Validate proof of work
-- **Chain Context**: Understand transaction position
-
-### Interoperability
-
-- **Standardized**: Consistent format across applications
-- **Portable**: Easy to transmit and store
-- **Compatible**: Works with SPV clients
-
-## Use Cases
-
-### Transaction Broadcasting
-
-```typescript
-// Broadcast transaction with proof
-const beefTx = Transaction.fromHexBEEF(beefData)
-await beefTx.broadcast(arcConfig)
-```
-
-### Data Exchange
-
-- Share transactions between applications
-- Provide verification data to SPV clients
-- Archive transactions with proofs
-
-### Wallet Integration
-
-- Import transactions with full context
-- Verify historical transactions
-- Synchronize between devices
-
-## BEEF Structure
-
-The format includes:
-
-1. **Version**: BEEF format version
-2. **Transactions**: One or more Bitcoin transactions
-3. **Proofs**: Merkle proofs for each transaction
-4. **Headers**: Relevant block headers
-5. **Metadata**: Additional application data
-
-## Best Practices
-
-- Use BEEF for transactions that need verification
-- Include minimal necessary proof data
-- Validate BEEF structure before processing
-- Cache parsed BEEF data for performance
-
-## Next Steps
-
-- Learn about [SPV Verification](./spv-verification.md) concepts
-- Understand [Transaction Encoding](./transaction-encoding.md) formats
-- Explore [Chain Tracking](./chain-tracking.md) integration

package/docs/concepts/chain-tracking.md

@@ -1,134 +0,0 @@
-# Chain Tracking
-
-How the BSV TypeScript SDK interacts with the Bitcoin network to retrieve transaction and blockchain data.
-
-## Chain Tracker Concept
-
-A chain tracker provides access to Bitcoin blockchain data without running a full node:
-
-```typescript
-import { WhatsOnChain } from '@bsv/sdk'
-
-// Create a chain tracker
-const chainTracker = new WhatsOnChain('mainnet')
-
-// Get transaction data
-const txData = await chainTracker.getTransaction('txid')
-```
-
-## Key Functions
-
-### Transaction Lookup
-
-- Retrieve transaction details by ID
-- Get transaction status and confirmations
-- Access transaction inputs and outputs
-
-### UTXO Queries
-
-- Find unspent transaction outputs
-- Check UTXO availability and value
-- Retrieve UTXO locking scripts
-
-### Block Information
-
-- Get block headers and merkle proofs
-- Verify transaction inclusion in blocks
-- Access block timestamps and difficulty
-
-### Network Status
-
-- Check network connectivity
-- Monitor chain tip and height
-- Get fee rate recommendations
-
-## SPV Integration
-
-Chain trackers enable SPV (Simplified Payment Verification):
-
-- **Merkle Proofs**: Verify transaction inclusion without full blocks
-- **Header Chain**: Maintain block headers for proof verification
-- **Lightweight**: Minimal data requirements compared to full nodes
-
-## Multiple Providers
-
-The SDK supports multiple chain tracking services:
-
-```typescript
-// Primary and fallback providers
-const config = {
-  chainTracker: {
-    provider: 'WhatsOnChain',
-    network: 'mainnet',
-    fallbacks: ['GorillaPool', 'TAAL']
-  }
-}
-```
-
-## Benefits
-
-### Scalability
-
-- No need to store the entire blockchain
-- Fast startup and synchronization
-- Minimal storage requirements
-
-### Reliability
-
-- Multiple provider support
-- Automatic failover capabilities
-- Redundant data sources
-
-### Performance
-
-- Targeted data queries
-- Caching of frequently accessed data
-- Optimized for application needs
-
-## Common Patterns
-
-### Transaction Verification
-
-```typescript
-// Verify a transaction exists
-const exists = await chainTracker.getTransaction(txid)
-if (exists) {
-  // Transaction is confirmed on-chain
-}
-```
-
-### UTXO Validation
-
-```typescript
-// Check if UTXO is still unspent
-const utxo = await chainTracker.getUTXO(txid, outputIndex)
-if (utxo) {
-  // UTXO is available for spending
-}
-```
-
-## Error Handling
-
-Chain tracker operations can fail due to:
-
-- Network connectivity issues
-- Service provider downtime
-- Invalid transaction IDs
-- Rate limiting
-
-The SDK provides automatic retry and failover mechanisms.
-
-## Configuration
-
-Chain trackers can be configured for:
-
-- **Network**: Mainnet, testnet, or regtest
-- **Endpoints**: Custom service URLs
-- **Timeouts**: Request timeout settings
-- **Retry Logic**: Failure handling behavior
-
-## Next Steps
-
-- Understand [SPV Verification](./spv-verification.md) concepts
-- Learn about [BEEF Format](./beef.md) for efficient data exchange
-- Explore [Trust Model](./trust-model.md) considerations

package/docs/concepts/decentralized-identity.md

@@ -1,221 +0,0 @@
-# Decentralized Identity
-
-Understanding how decentralized identity works in BSV and why it matters for building trustless applications.
-
-## What is Decentralized Identity?
-
-Imagine a world where you control your own identity credentials, just like you control your own wallet. Instead of relying on Facebook, Google, or government agencies to verify who you are, you can prove your identity using cryptographic certificates that anyone can independently verify.
-
-This is the promise of decentralized identity: **self-sovereign identity** that puts users in control while maintaining security and trust.
-
-## Why Decentralized Identity Matters
-
-### The Problem with Centralized Identity
-
-Traditional identity systems have significant limitations:
-
-- **Single Points of Failure**: If the identity provider goes down, you lose access
-- **Privacy Concerns**: Companies collect and monetize your personal data
-- **Vendor Lock-in**: You can't easily move your identity between services
-- **Censorship Risk**: Providers can revoke your identity for any reason
-- **Data Breaches**: Centralized databases are attractive targets for hackers
-
-### The Decentralized Solution
-
-Decentralized identity addresses these issues by:
-
-- **User Control**: You own and manage your identity data
-- **No Central Authority**: No single entity controls the verification process
-- **Interoperability**: Your identity works across different applications
-- **Privacy by Design**: You choose what information to reveal and when
-- **Censorship Resistance**: No one can arbitrarily revoke your identity
-
-## How It Works in BSV
-
-### Identity Keys vs Transaction Keys
-
-BSV uses different types of keys for different purposes:
-
-**Identity Keys** are long-term, stable identifiers used for:
-
-- Establishing your digital identity
-- Signing identity certificates
-- Resolving your public profile information
-- Authenticating with services
-
-**Transaction Keys** are used for:
-
-- Signing Bitcoin transactions
-- Managing UTXOs and payments
-- Protocol-specific operations
-
-This separation provides both security and privacy benefits.
-
-### Identity Resolution
-
-Your identity key serves as a unique identifier that can be used to discover:
-
-- Your chosen display name and profile information
-- Verification badges and trust indicators
-- Public certificates and credentials
-- Contact preferences and communication methods
-
-Think of it like a decentralized phone book where your identity key is your number, but instead of just finding your phone number, people can discover rich identity information that you've chosen to make public.
-
-### Certificate-Based Trust
-
-Instead of trusting a central authority, decentralized identity relies on a web of cryptographic certificates. These certificates are like digital testimonials that others can independently verify:
-
-- **Self-Signed Certificates**: Claims you make about yourself
-- **Peer Certificates**: Verifications from other users
-- **Institutional Certificates**: Credentials from recognized organizations
-- **Service Certificates**: Verifications from specialized services
-
-## Trust and Verification Models
-
-### Web of Trust
-
-In a web of trust model, users verify each other's identities, creating networks of trusted relationships. This is similar to how you might trust a friend's recommendation about a restaurant - the more trusted connections someone has, the more credible they become.
-
-### Institutional Trust
-
-Some applications require higher assurance levels, so they rely on certificates from recognized institutions like universities, professional licensing boards, or government agencies. These certificates carry more weight because the issuers have established reputations and verification processes.
-
-### Hybrid Approaches
-
-Most real-world applications use a combination of trust models, adjusting requirements based on context. For example:
-
-- **Low-risk interactions** might accept self-signed certificates
-- **Financial transactions** might require institutional verification
-- **Professional networking** might emphasize peer verification within industry groups
-
-## Privacy and Selective Disclosure
-
-### Controlling Your Information
-
-One of the key benefits of decentralized identity is granular control over your personal information. You can:
-
-- Choose which attributes to make publicly discoverable
-- Reveal different information to different parties
-- Prove claims without revealing underlying data
-- Revoke access to previously shared information
-
-### Zero-Knowledge Proofs
-
-Advanced cryptographic techniques allow you to prove things about yourself without revealing the underlying information. For example, you could prove you're over 21 without revealing your exact age or birthdate.
-
-### Progressive Disclosure
-
-As trust builds between parties, you might choose to reveal more information. This allows relationships to develop naturally while maintaining privacy protection.
-
-## Identity Lifecycle
-
-### Getting Started
-
-Creating a decentralized identity involves:
-
-1. **Generating an identity key pair** (handled by your wallet)
-2. **Creating basic profile information** (name, avatar, contact preferences)
-3. **Obtaining initial certificates** to establish credibility
-4. **Making your identity discoverable** through resolution networks
-
-### Building Trust
-
-Over time, you accumulate certificates and verifications that build your reputation:
-
-- Verify your email address and social media accounts
-- Get endorsements from colleagues and friends
-- Obtain professional certifications and credentials
-- Participate in community verification programs
-
-### Maintaining Privacy
-
-As your identity grows, you maintain control by:
-
-- Regularly reviewing what information is public
-- Updating privacy preferences as needs change
-- Revoking outdated or unwanted certificates
-- Managing consent for data sharing
-
-## Real-World Applications
-
-### Passwordless Authentication
-
-Instead of remembering dozens of passwords, you can authenticate using your identity certificates. This is more secure than passwords and eliminates the need for password managers.
-
-### Professional Networking
-
-Verify professional credentials, work history, and skills through cryptographic certificates rather than relying on self-reported information on traditional platforms.
-
-### Age and Identity Verification
-
-Prove your age for restricted services without revealing your exact birthdate, or verify your identity for account creation without sharing unnecessary personal information.
-
-### Reputation Systems
-
-Build portable reputation that follows you across different platforms and applications, creating incentives for good behavior and reducing fraud.
-
-### Decentralized Social Networks
-
-Participate in social networks where your identity and connections are owned by you, not the platform, enabling true social media portability.
-
-## Benefits for Developers
-
-### Simplified User Onboarding
-
-Instead of building complex registration and verification systems, applications can rely on existing identity infrastructure and certificates.
-
-### Enhanced Security
-
-Cryptographic identity verification is more secure than traditional username/password systems and reduces the risk of account takeovers.
-
-### Regulatory Compliance
-
-Decentralized identity can help meet KYC (Know Your Customer) and AML (Anti-Money Laundering) requirements while preserving user privacy.
-
-### Interoperability
-
-Users can bring their identity and reputation from other applications, reducing friction and improving user experience.
-
-## Challenges and Considerations
-
-### User Experience
-
-Decentralized identity requires users to understand new concepts like key management and certificate verification. Good wallet software and user interfaces are essential for adoption.
-
-### Recovery and Backup
-
-Unlike centralized systems where you can reset your password, losing access to your identity keys can be permanent. Robust backup and recovery mechanisms are crucial.
-
-### Network Effects
-
-The value of decentralized identity increases as more people and organizations participate. Early adoption requires overcoming the "chicken and egg" problem.
-
-### Scalability
-
-As identity networks grow, efficient resolution and verification mechanisms become increasingly important to maintain performance.
-
-## The Future of Identity
-
-Decentralized identity represents a fundamental shift toward user sovereignty and privacy. As the technology matures and adoption grows, we can expect to see:
-
-- **Seamless Integration** with everyday applications and services
-- **Enhanced Privacy Protection** through advanced cryptographic techniques
-- **Global Interoperability** across different identity systems and networks
-- **Reduced Identity Fraud** through cryptographic verification
-- **New Business Models** that respect user privacy and data ownership
-
-By understanding these concepts, developers can build applications that respect user privacy, enhance security, and contribute to a more open and decentralized internet.
-
-## Related Concepts
-
-- [Identity Certificates](./identity-certificates.md) - How cryptographic certificates enable trust
-- [Digital Signatures](./signatures.md) - Cryptographic foundations of identity verification
-- [Trust Model](./trust-model.md) - Security assumptions in decentralized systems
-- [Key Management](./key-management.md) - Managing cryptographic keys securely
-
-## Further Reading
-
-- [Identity Management Tutorial](../tutorials/identity-management.md) - Hands-on implementation guide
-- [AuthFetch Tutorial](../tutorials/authfetch-tutorial.md) - Authenticated communication using identity
-- [Security Best Practices](../guides/security-best-practices.md) - Secure identity implementation patterns