@bsv/sdk 1.6.12 → 1.6.14

package/docs/MARKDOWN_VALIDATION_GUIDE.md

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

@@ -5,6 +5,7 @@ Bitcoin Extras Extension Format (BEEF) - an efficient way to package Bitcoin tra
 ## 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
@@ -28,16 +29,19 @@ 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
@@ -45,6 +49,7 @@ const isValid = await tx.verify(chainTracker)
 ## Use Cases
 
 ### Transaction Broadcasting
+
 ```typescript
 // Broadcast transaction with proof
 const beefTx = Transaction.fromHexBEEF(beefData)
@@ -52,11 +57,13 @@ 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
@@ -64,6 +71,7 @@ await beefTx.broadcast(arcConfig)
 ## BEEF Structure
 
 The format includes:
+
 1. **Version**: BEEF format version
 2. **Transactions**: One or more Bitcoin transactions
 3. **Proofs**: Merkle proofs for each transaction

package/docs/concepts/chain-tracking.md

@@ -19,21 +19,25 @@ 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
@@ -41,6 +45,7 @@ const txData = await chainTracker.getTransaction('txid')
 ## 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
@@ -63,16 +68,19 @@ const config = {
 ## 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
@@ -80,6 +88,7 @@ const config = {
 ## Common Patterns
 
 ### Transaction Verification
+
 ```typescript
 // Verify a transaction exists
 const exists = await chainTracker.getTransaction(txid)
@@ -89,6 +98,7 @@ if (exists) {
 ```
 
 ### UTXO Validation
+
 ```typescript
 // Check if UTXO is still unspent
 const utxo = await chainTracker.getUTXO(txid, outputIndex)
@@ -100,6 +110,7 @@ if (utxo) {
 ## Error Handling
 
 Chain tracker operations can fail due to:
+
 - Network connectivity issues
 - Service provider downtime
 - Invalid transaction IDs
@@ -110,6 +121,7 @@ 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

package/docs/concepts/decentralized-identity.md

@@ -11,7 +11,9 @@ This is the promise of decentralized identity: **self-sovereign identity** that
 ## 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
@@ -19,7 +21,9 @@ Traditional identity systems have significant limitations:
 - **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
@@ -29,15 +33,18 @@ Decentralized identity addresses these issues by:
 ## 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
@@ -45,7 +52,9 @@ BSV uses different types of keys for different purposes:
 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
@@ -54,6 +63,7 @@ Your identity key serves as a unique identifier that can be used to discover:
 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
@@ -64,13 +74,17 @@ Instead of trusting a central authority, decentralized identity relies on a web
 ## 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
@@ -78,36 +92,46 @@ Most real-world applications use a combination of trust models, adjusting requir
 ## 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
@@ -116,46 +140,59 @@ As your identity grows, you maintain control by:
 ## 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

package/docs/concepts/fees.md

@@ -20,6 +20,7 @@ const customFee = tx.getFee(feePerKB)
 ## Fee Calculation
 
 Fees are calculated based on transaction size:
+
 - **Fee Rate**: Satoshis per kilobyte (sat/kB)
 - **Transaction Size**: Total bytes in serialized transaction
 - **Total Fee**: Size × Fee Rate
@@ -27,7 +28,9 @@ Fees are calculated based on transaction size:
 ## SDK Fee Handling
 
 ### Automatic Fee Calculation
+
 The SDK calculates fees automatically:
+
 ```typescript
 // Wallet handles fees automatically
 const wallet = new WalletClient()
@@ -41,7 +44,9 @@ const action = await wallet.createAction({
 ```
 
 ### Manual Fee Control
+
 For advanced use cases:
+
 ```typescript
 // Calculate fee manually
 const tx = new Transaction()
@@ -55,12 +60,15 @@ const feeRequired = estimatedSize * feePerByte
 ## Fee Rates
 
 ### Network Fee Rates
+
 BSV typically uses low, predictable fees:
+
 - **Standard Rate**: ~0.5 sat/byte
 - **Priority Rate**: ~1.0 sat/byte
 - **Economy Rate**: ~0.1 sat/byte
 
 ### Dynamic Fee Estimation
+
 ```typescript
 // Get current network fee rates
 const feeRates = await chainTracker.getFeeRates()
@@ -70,20 +78,26 @@ const recommendedFee = feeRates.standard
 ## Fee Components
 
 ### Input Costs
+
 Each input adds to transaction size:
+
 - Previous transaction hash (32 bytes)
 - Output index (4 bytes)
 - Unlocking script (variable)
 - Sequence number (4 bytes)
 
 ### Output Costs
+
 Each output adds to transaction size:
+
 - Value (8 bytes)
 - Locking script length (1-9 bytes)
 - Locking script (variable)
 
 ### Base Transaction
+
 Fixed overhead for every transaction:
+
 - Version (4 bytes)
 - Input count (1-9 bytes)
 - Output count (1-9 bytes)
@@ -92,7 +106,9 @@ Fixed overhead for every transaction:
 ## Fee Optimization
 
 ### UTXO Selection
+
 Choose UTXOs efficiently:
+
 ```typescript
 // Prefer fewer, larger UTXOs to reduce fees
 const utxos = await wallet.getUTXOs()
@@ -100,7 +116,9 @@ const selected = selectOptimalUTXOs(utxos, targetAmount)
 ```
 
 ### Output Consolidation
+
 Combine multiple payments:
+
 ```typescript
 // Batch multiple outputs in one transaction
 const outputs = [
@@ -111,7 +129,9 @@ const outputs = [
 ```
 
 ### Script Efficiency
+
 Use efficient script templates:
+
 ```typescript
 // P2PKH is more efficient than complex scripts
 const p2pkh = new P2PKH()
@@ -121,7 +141,9 @@ const efficientScript = p2pkh.lock(publicKeyHash)
 ## Fee Estimation
 
 ### Size Estimation
+
 Estimate transaction size before creation:
+
 ```typescript
 // Estimate size for fee calculation
 const estimatedInputs = 2
@@ -131,6 +153,7 @@ const estimatedFee = estimatedSize * feeRate
 ```
 
 ### Template-Based Estimation
+
 ```typescript
 // Use script templates for accurate estimation
 const template = new P2PKH()
@@ -140,6 +163,7 @@ const scriptSize = template.estimateLength([publicKeyHash])
 ## Error Handling
 
 Common fee-related issues:
+
 - Insufficient funds for fees
 - Fee rate too low for network
 - Transaction size miscalculation
@@ -160,18 +184,21 @@ try {
 ## Best Practices
 
 ### Fee Management
+
 - Always account for fees in balance calculations
 - Use appropriate fee rates for urgency
 - Monitor network conditions for fee adjustments
 - Implement fee estimation before transaction creation
 
 ### Cost Optimization
+
 - Batch transactions when possible
 - Use efficient script templates
 - Optimize UTXO selection
 - Consider transaction timing
 
 ### User Experience
+
 - Display estimated fees to users
 - Provide fee rate options (economy, standard, priority)
 - Handle insufficient fund errors gracefully
@@ -180,6 +207,7 @@ try {
 ## Wallet Integration
 
 Most applications rely on wallets for fee handling:
+
 ```typescript
 // Wallet manages fees automatically
 const wallet = new WalletClient()
@@ -194,7 +222,9 @@ const result = await wallet.createAction({
 ## Advanced Fee Strategies
 
 ### Replace-by-Fee (RBF)
+
 Increase fees for faster confirmation:
+
 ```typescript
 // Create transaction with RBF enabled
 const tx = new Transaction()
@@ -202,7 +232,9 @@ tx.setRBF(true) // Enable replace-by-fee
 ```
 
 ### Child-Pays-for-Parent (CPFP)
+
 Use dependent transactions to increase effective fee rate:
+
 ```typescript
 // Create child transaction with higher fee
 const childTx = new Transaction()