smartledger-bsv 3.3.1 → 3.3.3

package/docs/README.md

@@ -1,84 +1,112 @@
 # SmartLedger-BSV Documentation
 
-Comprehensive documentation for SmartLedger-BSV v3.1.1+ - Advanced Bitcoin SV Library with Enterprise Covenant Framework.
-
-## 📚 Documentation Structure
-
-### Core Guides
-- **[Getting Started](getting-started.md)** - Installation, setup, and first steps
-- **[API Reference](api-reference.md)** - Complete API documentation
-- **[Configuration Guide](configuration.md)** - Setup and optimization
-
-### Advanced Features
-- **[Advanced Covenant Development](ADVANCED_COVENANT_DEVELOPMENT.md)** - BIP143 + nChain PUSHTX techniques
-- **[Custom Script Development](CUSTOM_SCRIPT_DEVELOPMENT.md)** - Script creation patterns
-- **[Covenant Development Resolved](COVENANT_DEVELOPMENT_RESOLVED.md)** - Problem solutions and working examples
-
-### Technical Specifications
-- **[BIP143 Preimage Format](preimage.md)** - Detailed preimage structure specification
-- **[nChain PUSHTX Paper](nchain.md)** - Academic research integration (WP1605)
-- **[Security Best Practices](security-best-practices.md)** - Production guidelines
-
-## 🎯 Quick Navigation
-
-### New to SmartLedger-BSV?
-1. **[Getting Started](getting-started.md)** - Begin here for installation and basic usage
-2. **[Examples Directory](../examples/)** - Hands-on code examples
-3. **[Basic Usage](#basic-usage)** - Common patterns and workflows
-
-### Building Custom Scripts?
-1. **[Custom Script Development](CUSTOM_SCRIPT_DEVELOPMENT.md)** - Complete guide to script creation
-2. **[Script Examples](../examples/scripts/)** - Working code examples
-3. **[API Reference](api-reference.md)** - CustomScriptHelper documentation
-
-### Developing Covenants?
-1. **[Advanced Covenant Development](ADVANCED_COVENANT_DEVELOPMENT.md)** - Complete covenant framework
-2. **[Covenant Examples](../examples/covenants/)** - Working covenant patterns  
-3. **[BIP143 Specification](preimage.md)** - Preimage structure details
-4. **[nChain PUSHTX](nchain.md)** - Academic research foundation
-
-### Production Deployment?
-1. **[Security Best Practices](security-best-practices.md)** - Production guidelines
-2. **[Configuration Guide](configuration.md)** - Optimization and setup
-3. **[API Reference](api-reference.md)** - Complete API documentation
-
-## 🚀 Key Features Overview
-
-### Core Library Capabilities
-- **Complete BSV API**: Full compatibility with Bitcoin SV operations
-- **Ultra-Low Fees**: 0.01 sats/byte configuration (91% fee reduction)  
-- **UTXO Management**: Advanced state management with change outputs
-- **CDN Distribution**: Multiple webpack bundles for web development
-- **Security Hardened**: Enhanced elliptic curve security fixes
-
-### Advanced Covenant Framework
-- **BIP143 Compliant**: Complete preimage parsing with field-by-field access
-- **PUSHTX Integration**: nChain WP1605 in-script signature generation
-- **PELS Support**: Perpetually Enforcing Locking Scripts for ongoing rules
-- **Dual-Level API**: High-level abstractions with granular BSV control
-- **Production Ready**: Comprehensive validation and error handling
-
-### Custom Script Development
-- **Multi-signature Scripts**: Advanced m-of-n signature schemes
-- **Timelock Contracts**: Block height and timestamp constraints
-- **Conditional Logic**: Complex branching and validation rules
-- **Template System**: Pre-built patterns for common use cases
-- **Developer API**: Simplified interface for rapid development
-
-## 📖 Documentation Categories
-
-### 📦 Installation & Setup
-```javascript
-// NPM installation
-npm install @smartledger/bsv
-
-// Basic usage
-const bsv = require('@smartledger/bsv');
-const tx = new bsv.Transaction()
-  .from(utxo)
-  .to(address, amount)
-  .feePerKb(10); // Ultra-low fees
-```
+**The Standard Bitcoin SV Library - Enhanced, Hardened, and Extended**
+
+SmartLedger-BSV is a fully backward-compatible extension of bsv@1.5.6 with elliptic curve hardening and comprehensive additional modules for modern Bitcoin SV development.
+
+## 🎯 **What Makes SmartLedger-BSV the Standard**
+
+- **✅ 100% Backward Compatible** with bsv@1.5.6 - Drop-in replacement
+- **🛡️ Security Hardened** - Enhanced elliptic curve implementations  
+- **📦 12 Modular Loading Options** - Use only what you need
+- **⚖️ Legal Compliance Ready** - Built-in Legal Token Protocol (LTP)
+- **🌐 Digital Identity Native** - W3C standard DIDs and Verifiable Credentials
+- **🔐 Enterprise Security** - Shamir Secret Sharing and advanced cryptography
+- **🔒 Smart Contract Framework** - Complete covenant development toolkit
+- **📚 Production Ready** - Comprehensive documentation and examples
+
+## 📚 **Documentation Structure**
+
+### 🚀 **Getting Started**
+Perfect for developers new to Bitcoin SV or migrating from other libraries.
+
+- [**Quick Start Guide**](getting-started/QUICK_START.md) - Get running in 2 minutes
+- [**Installation & Setup**](getting-started/INSTALLATION.md) - All installation methods
+- [**Migration from bsv@1.5.6**](migration/FROM_BSV_1_5_6.md) - Seamless upgrade path
+- [**Migration from BitcoinJS**](migration/FROM_BITCOINJS.md) - Switch from BitcoinJS-lib
+- [**First Transaction**](getting-started/FIRST_TRANSACTION.md) - Hello World example
+
+### 📖 **Core API Guides** 
+Complete guides for standard Bitcoin SV operations.
+
+- [**Transactions**](api/TRANSACTIONS.md) - Create, sign, and broadcast transactions
+- [**Addresses & Keys**](api/ADDRESSES_KEYS.md) - Generate and manage Bitcoin addresses
+- [**Scripts**](api/SCRIPTS.md) - Bitcoin Script creation and execution
+- [**Networks**](api/NETWORKS.md) - Mainnet, testnet, and custom networks
+- [**ECIES Encryption**](api/ECIES.md) - Elliptic Curve encryption/decryption
+- [**Message Signing**](api/MESSAGE_SIGNING.md) - Sign and verify messages
+- [**HD Wallets**](api/HD_WALLETS.md) - Hierarchical Deterministic wallets
+
+### � **Advanced Features**
+Unique capabilities that set SmartLedger-BSV apart.
+
+- [**Legal Token Protocol (LTP)**](advanced/LEGAL_TOKEN_PROTOCOL.md) - Property rights & obligations
+- [**Global Digital Attestation (GDAF)**](advanced/DIGITAL_ATTESTATION.md) - DIDs & credentials
+- [**Shamir Secret Sharing**](advanced/SHAMIR_SECRET_SHARING.md) - Threshold cryptography
+- [**Smart Contract Framework**](advanced/SMART_CONTRACT_GUIDE.md) - Complete covenant development
+- [**UTXO Management**](advanced/UTXO_MANAGER_GUIDE.md) - Advanced UTXO operations
+- [**Custom Script Development**](advanced/CUSTOM_SCRIPT_DEVELOPMENT.md) - Build custom Bitcoin scripts
+
+### 🎓 **Developer Guides**
+Step-by-step tutorials for common development patterns.
+
+- [**Building a Wallet**](guides/BUILDING_WALLET.md) - Complete wallet implementation
+- [**Payment Processing**](guides/PAYMENT_PROCESSING.md) - Accept Bitcoin payments
+- [**Multi-signature Transactions**](guides/MULTISIG_TRANSACTIONS.md) - Multi-party security
+- [**Atomic Swaps**](guides/ATOMIC_SWAPS.md) - Trustless exchanges
+- [**Micropayment Channels**](guides/MICROPAYMENT_CHANNELS.md) - Payment channels
+- [**Data Storage on BSV**](guides/DATA_STORAGE.md) - Store data on-chain
+
+### 🔬 **Advanced Development**
+Production-ready patterns and advanced use cases.
+
+- [**Covenant Development**](advanced/ADVANCED_COVENANT_DEVELOPMENT.md) - Production covenant patterns
+- [**Smart Contract Security**](advanced/SMART_CONTRACT_SECURITY.md) - Security best practices  
+- [**Performance Optimization**](advanced/PERFORMANCE_OPTIMIZATION.md) - Scale your applications
+- [**Testing Strategies**](advanced/TESTING_STRATEGIES.md) - Comprehensive testing
+- [**Production Deployment**](advanced/PRODUCTION_DEPLOYMENT.md) - Deploy with confidence
+
+### 📋 **Examples & Templates**
+Ready-to-use code examples and project templates.
+
+- [**Basic Examples**](../examples/basic/) - Simple transaction examples
+- [**Smart Contract Examples**](../examples/covenants/) - Covenant patterns
+- [**Advanced Examples**](../examples/covenants2/) - Production patterns
+- [**Project Templates**](examples/TEMPLATES.md) - Starter projects
+
+### 🔧 **Troubleshooting & Support**
+Solutions to common issues and getting help.
+
+- [**Common Issues**](troubleshooting/COMMON_ISSUES.md) - Frequently encountered problems
+- [**Error Reference**](troubleshooting/ERROR_REFERENCE.md) - Complete error guide
+- [**Performance Issues**](troubleshooting/PERFORMANCE_ISSUES.md) - Optimization tips
+- [**Browser Compatibility**](troubleshooting/BROWSER_COMPATIBILITY.md) - Cross-browser support
+- [**Getting Support**](troubleshooting/GETTING_SUPPORT.md) - Community and help
+
+## 🔗 **Quick Navigation**
+
+**I want to...**
+- **Get started quickly** → [Quick Start Guide](getting-started/QUICK_START.md)
+- **Migrate from bsv@1.5.6** → [Migration Guide](migration/FROM_BSV_1_5_6.md)  
+- **Learn smart contracts** → [Smart Contract Guide](advanced/SMART_CONTRACT_GUIDE.md)
+- **Use legal tokens** → [Legal Token Protocol](advanced/LEGAL_TOKEN_PROTOCOL.md)
+- **Implement digital identity** → [Digital Attestation Guide](advanced/DIGITAL_ATTESTATION.md)
+- **Build a production app** → [Advanced Development](advanced/)
+- **See working examples** → [Examples Directory](../examples/)
+- **Get help** → [Troubleshooting](troubleshooting/)
+
+## � **Library Comparison**
+
+| Feature | SmartLedger-BSV | bsv@1.5.6 | BitcoinJS-lib |
+|---------|-----------------|-----------|---------------|
+| **Core BSV Support** | ✅ Full | ✅ Full | ❌ Bitcoin only |
+| **Backward Compatibility** | ✅ 100% | - | ❌ Different API |
+| **Security Hardening** | ✅ Yes | ❌ No | ❌ No |
+| **Legal Tokens** | ✅ Built-in | ❌ No | ❌ No |
+| **Digital Identity** | ✅ W3C Standard | ❌ No | ❌ No |
+| **Smart Contracts** | ✅ Complete Framework | ❌ Basic | ❌ No |
+| **Modular Loading** | ✅ 12 Options | ❌ Monolithic | ❌ Monolithic |
+| **Production Ready** | ✅ Yes | ⚠️ Limited | ⚠️ Bitcoin only |
 
 ### 🔒 Covenant Development
 ```javascript

package/docs/advanced/LEGAL_TOKEN_PROTOCOL.md

@@ -0,0 +1,411 @@
+# Legal Token Protocol (LTP)
+
+## What is LTP?
+
+The Legal Token Protocol (LTP) is SmartLedger-BSV's comprehensive framework for creating **legally interpretable digital tokens** that represent real-world rights, obligations, and legal relationships with cryptographic proof and blockchain anchoring.
+
+### Core Purpose
+
+LTP bridges the gap between **traditional legal concepts** and **blockchain technology** by:
+- **Digitizing Legal Rights**: Converting property titles, licenses, permits into cryptographically signed tokens
+- **Managing Legal Obligations**: Creating enforceable digital obligations with payment schedules and compliance tracking
+- **Ensuring Legal Compliance**: Providing jurisdiction-specific validation and regulatory compliance primitives
+- **Maintaining Audit Trails**: Creating immutable records of legal token lifecycle events
+
+### What Makes LTP Different
+
+Unlike simple utility tokens or NFTs, LTP tokens are designed to be **legally meaningful**:
+- **W3C Standards Compliant**: Built on Verifiable Credentials standard for interoperability
+- **Jurisdiction-Aware**: Supports different legal frameworks (US, EU, etc.)
+- **Privacy-Preserving**: Selective disclosure allows sharing only necessary information
+- **Legally Binding**: Designed to work within existing legal frameworks and courts
+
+## 🚀 Quick Start
+
+```javascript
+const bsv = require('@smartledger/bsv');
+
+// Create a property right token
+const ownerKey = new bsv.PrivateKey();
+const propertyData = {
+  type: 'PropertyTitle',
+  owner: 'did:smartledger:' + ownerKey.toPublicKey().toString(),
+  jurisdiction: 'US-CA',
+  property: {
+    address: '123 Main St, San Francisco, CA 94105',
+    parcelId: 'APN-12345678',
+    area: { value: 1000, unit: 'sqft' }
+  },
+  value: { amount: 850000, currency: 'USD' }
+};
+
+const propertyToken = bsv.createRightToken(propertyData, ownerKey, {
+  addProof: true,
+  anchor: false,
+  register: false
+});
+
+console.log('Token created:', propertyToken.success);
+console.log('Token ID:', propertyToken.token.id);
+```
+
+## 📚 Complete API Reference
+
+### Direct Token Functions
+
+#### `bsv.createRightToken(data, privateKey, options)`
+Creates a legal right token (property, vehicle, intellectual property, etc.)
+
+**Parameters:**
+- `data` - Token data object with type, owner, jurisdiction, and specific claim data
+- `privateKey` - PrivateKey instance for signing
+- `options` - Configuration options (addProof, anchor, register)
+
+**Returns:** `{ success: boolean, token: Object, type: string }`
+
+#### `bsv.verifyLegalToken(token, publicKey)`
+Verifies a legal token's cryptographic signature and validity
+
+**Parameters:**
+- `token` - Token object to verify
+- `publicKey` - Public key string for verification
+
+**Returns:** `{ valid: boolean, publicKey: string, tokenHash: string }`
+
+#### `bsv.validateLegalClaim(claimData, schemaType)`
+Validates claim data against legal schemas
+
+**Parameters:**
+- `claimData` - Claim object to validate
+- `schemaType` - Schema type ('PropertyTitle', 'VehicleTitle', etc.)
+
+**Returns:** `{ valid: boolean, schema: string, requiredFields?: Array }`
+
+#### `bsv.createSelectiveDisclosure(token, revealedFields, nonce)`
+Creates selective disclosure proof for privacy protection
+
+**Parameters:**
+- `token` - Token to create disclosure proof for
+- `revealedFields` - Array of field paths to reveal
+- `nonce` - Unique nonce string
+
+**Returns:** `{ success: boolean, proof: Object, disclosures: Array }`
+
+#### `bsv.createLegalRegistry(config)`
+Creates legal token registry configuration
+
+**Parameters:**
+- `config` - Registry configuration object
+
+**Returns:** Registry configuration object
+
+#### `bsv.createLegalValidityProof(token, jurisdiction, nonce)`
+Creates legal validity proof for compliance
+
+**Parameters:**
+- `token` - Token to validate
+- `jurisdiction` - Jurisdiction rules object
+- `nonce` - Unique nonce string
+
+**Returns:** `{ success: boolean, proof: Object, valid: boolean }`
+
+### LTP Class Interface
+
+```javascript
+const ltp = new bsv.LTP();
+
+// Transfer a right token
+const transfer = ltp.transferRight(token, newOwnerDID, ownerKey, {
+  reason: 'Sale',
+  consideration: { amount: 875000, currency: 'USD' }
+});
+
+// Create obligation from right
+const obligation = ltp.createObligation(rightToken, obligationData, privateKey);
+```
+
+### Primitives-Only Architecture
+
+For maximum flexibility, use the preparation functions that return data for external systems to handle:
+
+```javascript
+// Prepare right token (no blockchain interaction)
+const rightPrep = bsv.prepareRightToken(
+  'PropertyTitle',
+  issuerDID,
+  subjectDID,
+  claimData,
+  issuerPrivateKey,
+  options
+);
+
+// Prepare obligation token
+const obligationPrep = bsv.prepareObligationToken(
+  'PaymentObligation',
+  issuerDID,
+  obligorDID,
+  obligationData,
+  issuerPrivateKey,
+  options
+);
+
+// Prepare selective disclosure proof
+const disclosurePrep = bsv.prepareSelectiveDisclosure(
+  token,
+  revealedFields,
+  nonce
+);
+```
+
+## 🏗️ Architecture & Module Integration
+
+### How LTP Integrates with SmartLedger-BSV
+
+LTP is built on top of SmartLedger-BSV's modular architecture and integrates seamlessly with other modules:
+
+#### **Foundation Layer (Required)**
+- **Core BSV (`bsv.min.js`)**: Provides Bitcoin SV primitives (keys, transactions, addresses)
+- **Cryptographic Functions**: Uses hardened elliptic curve implementations for all signatures
+
+#### **Identity Layer (Recommended)**  
+- **GDAF Module (`bsv-gdaf.min.js`)**: Provides DID creation and Verifiable Credential standards
+- **Integration**: LTP tokens reference DIDs for issuers, subjects, and obligors
+
+#### **Smart Contract Layer (Optional)**
+- **Smart Contract Module (`bsv-smartcontract.min.js`)**: Provides covenant enforcement
+- **Integration**: LTP tokens can be protected by smart contract covenants for automatic enforcement
+
+#### **Security Layer (Optional)**
+- **Shamir Module (`bsv-shamir.min.js`)**: Provides threshold cryptography  
+- **Integration**: Can split LTP token signing keys across multiple parties
+
+#### **Privacy Layer (Built-in)**
+- **Selective Disclosure**: Native privacy-preserving proofs within LTP
+- **ECIES Encryption**: Uses core BSV ECIES for encrypted data fields
+
+### Primitives-Only Design Philosophy
+
+LTP follows SmartLedger-BSV's **primitives-only architecture**:
+
+**What LTP Provides (Preparation Functions):**
+- ✅ **Legal Structure Validation**: Ensures tokens follow legal standards
+- ✅ **Cryptographic Proof Generation**: Creates verifiable signatures and proofs  
+- ✅ **Compliance Checking**: Validates against jurisdiction-specific rules
+- ✅ **Token Lifecycle Management**: Handles creation, transfer, and revocation
+- ✅ **Registry Data Formatting**: Prepares data for external registry systems
+- ✅ **Blockchain Commitment Preparation**: Creates anchoring data without publishing
+
+**What External Systems Handle:**
+- 🔗 **Blockchain Publishing**: Your application publishes to BSV blockchain
+- 🔗 **Registry Storage**: Your database/registry stores token data
+- 🔗 **Network Communication**: Your API handles network requests
+- 🔗 **User Interfaces**: Your frontend displays and manages tokens
+- 🔗 **Business Logic**: Your application handles domain-specific workflows
+
+### Benefits of This Architecture
+- **Maximum Flexibility**: Use any blockchain, database, or UI framework
+- **No Vendor Lock-in**: Not tied to specific platforms or services
+- **Enterprise Ready**: Clean separation allows enterprise integration
+- **Legal Compliance**: Focus on legal correctness without implementation constraints
+
+## 📋 What LTP Can Tokenize
+
+### Real-World Legal Rights (Right Tokens)
+- **🏠 PropertyTitle** - Real estate ownership, deeds, titles
+- **🚗 VehicleTitle** - Car, boat, aircraft ownership documents
+- **💡 IntellectualProperty** - Patents, trademarks, copyrights
+- **🎵 MusicLicense** - Music publishing, performance rights
+- **💻 SoftwareLicense** - Software usage, distribution rights
+- **💰 FinancialInstrument** - Bonds, stocks, derivatives
+- **📄 PromissoryNote** - IOUs, payment promises
+- **🏅 ProfessionalLicense** - Professional certifications, permits
+- **🎫 AccessRight** - Membership rights, access permissions
+- **🗳️ VotingRight** - Shareholder voting, governance rights
+
+### Real-World Legal Obligations (Obligation Tokens)
+- **💵 PaymentObligation** - Loan payments, rent, mortgages
+- **📦 DeliveryObligation** - Shipping, delivery requirements
+- **🔧 MaintenanceObligation** - Maintenance contracts, warranties
+- **📊 ComplianceObligation** - Regulatory reporting, compliance
+- **📋 ReportingObligation** - Financial reporting, disclosures
+- **🤐 ConfidentialityObligation** - NDAs, confidentiality agreements
+- **🚫 NonCompeteObligation** - Non-compete agreements
+- **🛡️ WarrantyObligation** - Product warranties, guarantees
+
+### Module Relationships
+
+Each token type leverages different SmartLedger-BSV capabilities:
+
+```javascript
+// Property title using multiple modules
+const propertyToken = bsv.createRightToken({
+  type: 'PropertyTitle',              // LTP: Legal structure
+  owner: ownerDID,                    // GDAF: Digital identity  
+  jurisdiction: 'US-CA',              // LTP: Legal compliance
+  // Signed with hardened crypto     // Core: Enhanced security
+  // Can be covenant-protected       // SmartContract: Enforcement
+  // Keys can use Shamir sharing     // Shamir: Distributed control
+});
+```
+
+## � LTP Internal Architecture
+
+LTP is composed of 6 specialized modules working together:
+
+### Core Modules (`lib/ltp/`)
+
+1. **`right.js`** - Legal rights token creation and validation
+   - Creates property titles, licenses, permits
+   - Handles token transfers and ownership changes
+   - Validates right types and legal structures
+
+2. **`obligation.js`** - Legal obligation token management  
+   - Creates payment, delivery, compliance obligations
+   - Tracks obligation lifecycle and fulfillment
+   - Manages breach detection and remediation
+
+3. **`claim.js`** - Legal claim validation and attestation
+   - Validates claims against legal schemas
+   - Provides attestation and notarization primitives
+   - Handles bulk claim processing
+
+4. **`proof.js`** - Cryptographic proof generation
+   - Creates signature proofs for authenticity
+   - Generates selective disclosure proofs for privacy
+   - Produces legal validity proofs for compliance
+   - Handles zero-knowledge proofs for sensitive data
+
+5. **`registry.js`** - Token registry management
+   - Prepares registry configurations and policies
+   - Handles token registration and approval workflows
+   - Manages revocation and status tracking
+   - Provides search and audit capabilities
+
+6. **`anchor.js`** - Blockchain anchoring preparation
+   - Prepares commitment hashes for blockchain storage
+   - Handles batch anchoring for efficiency
+   - Creates merkle proofs for token verification
+   - Formats revocation data for on-chain publishing
+
+### How These Work Together
+
+```javascript
+// Complete workflow using all 6 modules
+const claim = bsv.LTP.Claim.validate(propertyData, 'PropertyTitle');     // 1. Validate
+const rightToken = bsv.LTP.Right.create(claim, ownerKey);               // 2. Create right  
+const obligation = bsv.LTP.Obligation.create(rightToken, taxData);      // 3. Create obligation
+const proof = bsv.LTP.Proof.createSignature(rightToken, issuerKey);     // 4. Generate proof
+const registry = bsv.LTP.Registry.register(rightToken);                 // 5. Prepare registry
+const anchor = bsv.LTP.Anchor.prepareCommitment(rightToken);            // 6. Prepare anchoring
+```
+
+## 🔐 Security & Trust Features
+
+- **🔒 Cryptographic Signatures** - All tokens signed with enhanced elliptic curves
+- **🎭 Selective Disclosure** - Privacy-preserving proof generation with zero-knowledge
+- **⚖️ Legal Validity Proofs** - Jurisdiction-specific compliance verification
+- **⛓️ Blockchain Anchoring** - Immutable commitment proofs on BSV blockchain
+- **📚 Registry Management** - Complete token lifecycle tracking and audit trails
+- **🛡️ Smart Contract Protection** - Optional covenant enforcement for automatic compliance
+- **🔑 Multi-Signature Support** - Shamir secret sharing for distributed key management
+
+## 🎯 Real-World Applications
+
+LTP integrates with other SmartLedger-BSV modules for complete enterprise solutions:
+
+### 🏡 Real Estate & Property Management
+```javascript
+// Complete property title system with GDAF identity verification
+const identity = bsv.GDAF.createIdentity(ownerData);                    // Identity layer
+const titleClaim = bsv.LTP.Claim.validate(propertyData, 'RealEstate'); // Legal validation
+const propertyTitle = bsv.LTP.Right.create(titleClaim, ownerKey);      // Create title token
+const transferCovenant = bsv.SmartContract.createCovenant(titleRules); // Smart enforcement
+const sharedKey = bsv.Shamir.split(ownerKey, 3, 5);                   // Distributed security
+```
+
+### 💼 Corporate Governance & Compliance
+```javascript  
+// Business license with automatic compliance monitoring
+const businessLicense = bsv.LTP.Right.create(licenseData, corporateKey);
+const complianceObligation = bsv.LTP.Obligation.create(license, regulations);
+const auditCovenant = bsv.SmartContract.createAuditContract(complianceRules);
+const executiveKeys = bsv.Shamir.split(corporateKey, 3, 7);
+```
+
+### 🏦 Financial Services & Banking
+```javascript
+// Loan agreement with payment automation
+const loanObligation = bsv.LTP.Obligation.create(loanTerms, borrowerKey);
+const paymentCovenant = bsv.SmartContract.createPaymentSchedule(terms);
+const creditProof = bsv.LTP.Proof.createSignature(creditData, bankKey);
+const escrowKeys = bsv.Shamir.split(escrowKey, 2, 3);
+```
+
+### 🎓 Education & Professional Certification
+```javascript
+// Academic credential with verification
+const degreeData = bsv.GDAF.createCredential(graduateData);
+const degreeClaim = bsv.LTP.Claim.validate(degreeData, 'AcademicDegree');
+const diploma = bsv.LTP.Right.create(degreeClaim, universityKey);
+const verificationProof = bsv.LTP.Proof.createValidity(diploma, accreditorKey);
+```
+
+### 🚛 Supply Chain & Logistics
+```javascript
+// Delivery tracking with quality assurance
+const deliveryObligation = bsv.LTP.Obligation.create(shipmentData, supplierKey);
+const qualityContract = bsv.SmartContract.createQualityGates(standards);
+const trackingProof = bsv.LTP.Proof.createSignature(locationData, carrierKey);
+const insuranceKeys = bsv.Shamir.split(insuranceKey, 2, 4);
+```
+
+### 🏛️ Government & Public Services
+```javascript
+// Government permit with regulatory compliance
+const permitData = bsv.GDAF.createGovernmentID(citizenData);
+const permitClaim = bsv.LTP.Claim.validate(permitData, 'BuildingPermit');
+const buildingPermit = bsv.LTP.Right.create(permitClaim, governmentKey);
+const complianceContract = bsv.SmartContract.createRegulatoryContract(codes);
+```
+
+## 📋 Token Type Categories
+
+### Right Tokens 🏆
+- **Property Titles** - Real estate, vehicles, patents, trademarks
+- **Business Licenses** - Professional, operational, regulatory permits  
+- **Access Rights** - Security, membership, usage privileges
+- **Intellectual Property** - Copyrights, licensing agreements, royalties
+
+### Obligation Tokens 📝
+- **Payment Obligations** - Invoices, loans, payment schedules, bonds
+- **Delivery Obligations** - Supply contracts, service agreements, milestones
+- **Compliance Obligations** - Regulatory, audit, reporting requirements
+- **Performance Obligations** - SLAs, quality standards, warranty terms
+
+### Legal Claims 🎖️
+- **Identity Claims** - Certifications, credentials, qualifications, clearances
+- **Property Claims** - Ownership, liens, encumbrances, easements  
+- **Performance Claims** - Warranties, guarantees, quality assurance
+- **Compliance Claims** - Regulatory adherence, audit results, certifications
+
+## 📖 Examples
+
+See the working demonstration files:
+- `demos/ltp_demo.js` - Complete LTP workflow
+- `demos/ltp_primitives_demo.js` - Primitives-only architecture
+- `demos/complete_ltp_demo.js` - End-to-end with real BSV keys
+
+## 🌐 W3C Compliance
+
+All LTP tokens follow W3C Verifiable Credential standards with SmartLedger extensions for legal compliance and Bitcoin SV blockchain integration.
+
+## ⚖️ Legal Framework
+
+The Legal Token Protocol is designed to work within existing legal frameworks and provides primitives for:
+- Legal claim attestation and validation
+- Jurisdictional compliance checking
+- Regulatory proof generation
+- Audit trail preparation
+- Right and obligation lifecycle management
+
+For trust law integration, see [Trust Protocol Mapping](../technical/trust_law.md).