@bsv/sdk 1.9.3 → 1.9.4

package/dist/cjs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.9.3",
+  "version": "1.9.4",
   "type": "commonjs",
   "description": "BSV Blockchain Software Development Kit",
   "files": [

package/docs/index.md

@@ -2,71 +2,76 @@
 
 ## SDK Overview
 
-The BSV TypeScript SDK is designed to provide an updated and unified layer for developing scalable applications on the BSV Blockchain. It addresses the limitations of previous tools by offering a fresh, peer-to-peer approach, adhering to SPV principles, and ensuring privacy and scalability.
+The BSV TypeScript SDK is designed to provide an updated and unified layer for developing scalable applications on the BSV Blockchain. It addresses the limitations of previous tools by offering a Direct Instant Payments (DIP) approach, ensuring privacy and scalability.
 
-This documentation is organized to help you learn, solve problems, understand concepts, and find technical references.
+## Installation
 
-## Documentation Categories
+To install the SDK, run:
 
-### [🚀 Tutorials](./tutorials/index.md)
+```bash
+npm install @bsv/sdk
+```
 
-Learn step-by-step with practical, guided examples:
+You can then import modules from the SDK as follows:
 
-- [Your First BSV Transaction](./tutorials/first-transaction.md)
-- [Key Management and Cryptography](./tutorials/key-management.md)
-- [Transaction Broadcasting and ARC](./tutorials/transaction-broadcasting.md)
-- [View all tutorials →](./tutorials/index.md)
+```ts
+import { WalletClient, PrivateKey, Transaction } from "@bsv/sdk";
+```
 
-### [🔧 How-To Guides](./guides/index.md)
+Or using require syntax:
 
-Problem-oriented guides for specific tasks:
+```js
+const { WalletClient, PrivateKey, Transaction } = require("@bsv/sdk");
+```
 
-- [Creating Multi-signature Transactions](./guides/multisig-transactions.md)
-- [Implementing Transaction Batching](./guides/transaction-batching.md)
-- [Configuring Custom ARC Endpoints](./guides/custom-arc-endpoints.md)
-- [View all guides →](./guides/index.md)
 
-### [📚 Reference](./reference/index.md)
+## BRC-100 Application to Wallet Interface
 
-Complete technical specifications and API documentation:
+This interface is what most application developers will use to interact with the BSV blockchain.
 
-- [BRC-100 Wallet Interface (Swagger)](./reference/brc-100.md)
-- [Primitives](./reference/primitives.md)
-- [Script](./reference/script.md)
-- [Transaction](./reference/transaction.md)
-- [View all references →](./reference/index.md)
+🚀 **[WalletClient Quickstart](https://fast.brc.dev/)**
 
-### [🏗️ Concepts & Explanations](./concepts/index.md)
+- Run SDK code examples without any setup
+- Experiment with transactions, keys, and scripts in real-time  
+- Learn by doing with immediate feedback
+- Test concepts from our tutorials interactively
 
-Understanding the architecture and design principles:
+[![alt text](fast-docs.png)](https://fast.brc.dev/)
 
-- [SDK Design Philosophy](./concepts/sdk-philosophy.md)
-- [Transaction Structure](./concepts/transaction-structure.md)
-- [SPV Verification](./concepts/spv-verification.md)
-- [BEEF Format](./concepts/beef.md)
-- [View all concepts →](./concepts/index.md)
+Perfect for getting started quickly or experimenting with new ideas.
 
-## Getting Started
+Another way to familiarize yourself with the Application to Wallet Interface is to checkout this Swagger UI.
 
-If you're new to the BSV TypeScript SDK, we recommend starting with our [Getting Started Tutorial](./tutorials/first-transaction.md).
+[![Swagger](swagger.png)](./swagger/index.html)
 
-## Try It Interactive
+Finally, you can deep dive into the details of the interface and types in the reference material below.
 
-🚀 **[Interactive BSV Coding Environment](https://fast.brc.dev/)**
+## Reference Material
 
-Experience the BSV TypeScript SDK directly in your browser! Our interactive coding environment lets you:
+- [Wallet](./reference/wallet.md)
+- [Primitives](./reference/primitives.md)
+- [Script](./reference/script.md)
+- [Transaction](./reference/transaction.md)
+- [Mutual Authenitcation](./reference/auth.md)
+- [Identity](./reference/identity.md)
+- [Overlay Tools](./reference/overlay-tools.md)
+- [Registry](./reference/registry.md)
+- [Storage](./reference/storage.md)
+- [KV Store](./reference/kvstore.md)
+- [Messages](./reference/messages.md)
+- [TOTP](./reference/totp.md)
+- [Compatibility](./reference/compat.md)
 
-- Run SDK code examples without any setup
-- Experiment with transactions, keys, and scripts in real-time  
-- Learn by doing with immediate feedback
-- Test concepts from our tutorials interactively
 
-Perfect for getting started quickly or experimenting with new ideas.
+## Coming Soon™
 
-## Installation
+- [Manual Transaction Creation](#manual-transaction-creation)
+- [Broadcasting Transactions](#broadcasting-transactions)
+- [Deriving Keys](#deriving-keys)
+- [Overlays](#overlays)
+- [MessageBox](#message-box)
 
-To install the SDK, run:
 
-```bash
-npm install @bsv/sdk
-```
+## Performance Reports
+
+- [Benchmarks](./performance.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.9.3",
+  "version": "1.9.4",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

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