@bsv/sdk 1.9.2 → 1.9.4

package/docs/concepts/fees.md

@@ -1,249 +0,0 @@
-# Transaction Fees
-
-Understanding Bitcoin transaction fees and how they work in the BSV TypeScript SDK.
-
-## What are Transaction Fees?
-
-Transaction fees are payments to miners for including transactions in blocks:
-
-```typescript
-import { Transaction } from '@bsv/sdk'
-
-// Calculate transaction fee
-const tx = new Transaction()
-const feeRequired = tx.getFee()
-
-// Set custom fee rate
-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
-
-## SDK Fee Handling
-
-### Automatic Fee Calculation
-
-The SDK calculates fees automatically:
-
-```typescript
-// Wallet handles fees automatically
-const wallet = new WalletClient()
-const action = await wallet.createAction({
-  outputs: [{
-    satoshis: 1000,
-    lockingScript: script
-  }]
-})
-// Fee calculated and deducted automatically
-```
-
-### Manual Fee Control
-
-For advanced use cases:
-
-```typescript
-// Calculate fee manually
-const tx = new Transaction()
-tx.addInput(/* input */)
-tx.addOutput(/* output */)
-
-const estimatedSize = tx.getSerializedSize()
-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()
-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)
-- Lock time (4 bytes)
-
-## Fee Optimization
-
-### UTXO Selection
-
-Choose UTXOs efficiently:
-
-```typescript
-// Prefer fewer, larger UTXOs to reduce fees
-const utxos = await wallet.getUTXOs()
-const selected = selectOptimalUTXOs(utxos, targetAmount)
-```
-
-### Output Consolidation
-
-Combine multiple payments:
-
-```typescript
-// Batch multiple outputs in one transaction
-const outputs = [
-  { satoshis: 1000, lockingScript: script1 },
-  { satoshis: 2000, lockingScript: script2 },
-  { satoshis: 1500, lockingScript: script3 }
-]
-```
-
-### Script Efficiency
-
-Use efficient script templates:
-
-```typescript
-// P2PKH is more efficient than complex scripts
-const p2pkh = new P2PKH()
-const efficientScript = p2pkh.lock(publicKeyHash)
-```
-
-## Fee Estimation
-
-### Size Estimation
-
-Estimate transaction size before creation:
-
-```typescript
-// Estimate size for fee calculation
-const estimatedInputs = 2
-const estimatedOutputs = 3
-const estimatedSize = estimateTransactionSize(estimatedInputs, estimatedOutputs)
-const estimatedFee = estimatedSize * feeRate
-```
-
-### Template-Based Estimation
-
-```typescript
-// Use script templates for accurate estimation
-const template = new P2PKH()
-const scriptSize = template.estimateLength([publicKeyHash])
-```
-
-## Error Handling
-
-Common fee-related issues:
-
-- Insufficient funds for fees
-- Fee rate too low for network
-- Transaction size miscalculation
-
-```typescript
-try {
-  const action = await wallet.createAction({
-    outputs: outputs
-  })
-} catch (error) {
-  if (error.message.includes('Insufficient funds')) {
-    // Handle insufficient balance for fees
-    console.log('Not enough funds to cover transaction and fees')
-  }
-}
-```
-
-## 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
-- Show fee breakdown for transparency
-
-## Wallet Integration
-
-Most applications rely on wallets for fee handling:
-
-```typescript
-// Wallet manages fees automatically
-const wallet = new WalletClient()
-
-// Fees are calculated and deducted automatically
-const result = await wallet.createAction({
-  description: 'Payment with automatic fees',
-  outputs: [/* outputs */]
-})
-```
-
-## Advanced Fee Strategies
-
-### Replace-by-Fee (RBF)
-
-Increase fees for faster confirmation:
-
-```typescript
-// Create transaction with RBF enabled
-const tx = new Transaction()
-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()
-childTx.addInput(/* from parent transaction */)
-// Higher fee rate pulls parent transaction along
-```
-
-## Next Steps
-
-- Understand [Transaction Structure](./transaction-structure.md) for size calculation
-- Learn about [Wallet Integration](./wallet-integration.md) for automatic fee handling
-- Explore [Script Templates](./script-templates.md) for efficient fee optimization

package/docs/concepts/identity-certificates.md

@@ -1,307 +0,0 @@
-# Identity Certificates
-
-Understanding how cryptographic certificates work to establish trust and verify identity claims in decentralized systems.
-
-## What are Identity Certificates?
-
-Think of identity certificates as digital testimonials that can't be forged. Just like a diploma proves you graduated from a university, or a driver's license proves you're authorized to drive, identity certificates prove specific claims about who you are or what you're authorized to do.
-
-The key difference is that these digital certificates use cryptographic signatures instead of physical security features, making them verifiable by anyone with the right tools, anywhere in the world.
-
-## How Certificates Create Trust
-
-### The Trust Problem
-
-In the digital world, it's easy to claim anything about yourself. Anyone can create a website saying they're a doctor, lawyer, or certified professional. How do you know who to trust?
-
-### The Certificate Solution
-
-Certificates solve this by having trusted third parties vouch for specific claims. When a university issues you a digital diploma certificate, they're cryptographically signing a statement that says "We verify that this person graduated from our program."
-
-Anyone can then verify:
-
-1. **The certificate is authentic** (cryptographic signature is valid)
-2. **It hasn't been tampered with** (any changes would break the signature)
-3. **It's still valid** (hasn't expired or been revoked)
-4. **The issuer is trustworthy** (you trust the university)
-
-## Types of Certificates
-
-### Self-Signed Certificates
-
-These are claims you make about yourself, like "My name is John Doe" or "My email is <john@example.com>." While anyone can create these, they serve as a starting point for building your digital identity.
-
-**When they're useful:**
-
-- Basic profile information
-- Contact preferences
-- Personal statements
-- Starting point for identity building
-
-**Limitations:**
-
-- Low trust value (anyone can claim anything)
-- Not suitable for high-stakes verification
-- Mainly useful for discovery and basic interaction
-
-### Peer-Verified Certificates
-
-These are endorsements from other users who can vouch for specific claims about you. Like professional references or character witnesses, they carry more weight when they come from trusted sources.
-
-**Examples:**
-
-- Colleague endorsing your professional skills
-- Friend confirming your identity
-- Community member vouching for your reputation
-- Business partner confirming successful transactions
-
-### Institutional Certificates
-
-These come from recognized organizations with established authority and verification processes. They carry the most weight because the issuers have reputations to protect and rigorous verification procedures.
-
-**Examples:**
-
-- University degree certificates
-- Professional licensing board certifications
-- Government-issued identity documents
-- Industry association memberships
-- Employer verification of work history
-
-## Certificate Lifecycle
-
-### Creation and Issuance
-
-When someone wants to issue you a certificate, they typically:
-
-1. **Verify your claim** through their established process
-2. **Create a digital certificate** containing the verified information
-3. **Sign it cryptographically** using their private key
-4. **Deliver it to you** for use in proving the claim
-
-### Validation and Trust
-
-When someone wants to verify your certificate, they:
-
-1. **Check the cryptographic signature** to ensure authenticity
-2. **Verify it hasn't expired** or been revoked
-3. **Assess the issuer's credibility** and authority
-4. **Determine if it meets their requirements** for the specific use case
-
-### Renewal and Maintenance
-
-Certificates have limited lifespans for security reasons:
-
-- **Expiration dates** ensure information stays current
-- **Renewal processes** allow for re-verification
-- **Revocation mechanisms** handle compromised or invalid certificates
-- **Update procedures** accommodate changing information
-
-## Trust Scoring and Reputation
-
-### Building Credibility
-
-Your overall trustworthiness comes from the combination of all your certificates:
-
-- **Quantity**: More verifications generally increase trust
-- **Quality**: Certificates from respected issuers carry more weight
-- **Diversity**: Different types of verification provide broader confidence
-- **Recency**: Fresh certificates are more valuable than old ones
-
-### Confidence Levels
-
-Different certificates provide different levels of assurance:
-
-- **Self-asserted claims** provide basic information but low confidence
-- **Peer verifications** offer moderate confidence from social proof
-- **Service verifications** provide higher confidence from specialized validators
-- **Institutional certificates** offer the highest confidence from established authorities
-
-### Context Matters
-
-The same certificate might be highly valuable in one context but irrelevant in another:
-
-- A medical license is crucial for healthcare but irrelevant for software development
-- A GitHub contribution history matters for programming jobs but not for teaching
-- Age verification is essential for restricted services but unnecessary for professional networking
-
-## Privacy and Selective Disclosure
-
-### Controlling Information Flow
-
-One of the key advantages of certificate-based identity is granular control over what you reveal:
-
-- **Public certificates** are discoverable by anyone
-- **Private certificates** are shared only with specific parties
-- **Selective revelation** lets you prove specific claims without revealing everything
-- **Progressive disclosure** allows trust to build gradually
-
-### Zero-Knowledge Proofs
-
-Advanced techniques allow you to prove things without revealing the underlying data:
-
-- Prove you're over 21 without revealing your exact age
-- Prove you have a degree without revealing which university
-- Prove you're a resident without revealing your exact address
-- Prove you're qualified without revealing all your credentials
-
-### Consent and Control
-
-You maintain control over your certificates:
-
-- **Choose what to make public** vs. keep private
-- **Decide who can access** specific information
-- **Revoke access** when relationships change
-- **Update preferences** as your needs evolve
-
-## Real-World Applications
-
-### Professional Verification
-
-Instead of relying on self-reported resumes, employers can verify:
-
-- Educational credentials directly from institutions
-- Work history from previous employers
-- Professional certifications from licensing bodies
-- Skills endorsements from colleagues and clients
-
-### Age and Identity Verification
-
-Services requiring age or identity verification can:
-
-- Verify age without collecting birthdates
-- Confirm identity without storing personal documents
-- Meet regulatory requirements while preserving privacy
-- Reduce fraud through cryptographic verification
-
-### Reputation Systems
-
-Platforms can build more reliable reputation systems:
-
-- Portable reputation that follows users between platforms
-- Verifiable transaction history and feedback
-- Reduced fake accounts and manipulation
-- Incentives for honest behavior
-
-### Access Control
-
-Organizations can manage access more securely:
-
-- Verify membership or employment status
-- Confirm professional qualifications
-- Validate security clearances
-- Authenticate without passwords
-
-## Benefits Over Traditional Systems
-
-### Security
-
-- **Cryptographic verification** is more secure than physical documents
-- **Tamper evidence** makes forgery virtually impossible
-- **Distributed validation** eliminates single points of failure
-- **Revocation mechanisms** handle compromised credentials quickly
-
-### Privacy
-
-- **Minimal disclosure** reveals only necessary information
-- **User control** over what information is shared
-- **No central databases** to be breached or misused
-- **Consent-based sharing** puts users in control
-
-### Interoperability
-
-- **Standard formats** work across different systems
-- **Portable credentials** move between applications
-- **Universal verification** works anywhere in the world
-- **Cross-platform compatibility** reduces vendor lock-in
-
-### Efficiency
-
-- **Automated verification** reduces manual processes
-- **Real-time validation** provides instant results
-- **Reduced paperwork** streamlines credential management
-- **Lower costs** compared to traditional verification methods
-
-## Challenges and Considerations
-
-### User Experience
-
-Making certificate systems user-friendly requires:
-
-- **Intuitive interfaces** that hide complexity
-- **Clear explanations** of what certificates mean
-- **Simple management tools** for organizing credentials
-- **Seamless integration** with existing workflows
-
-### Recovery and Backup
-
-Unlike traditional documents, losing access to digital certificates can be permanent:
-
-- **Backup strategies** are essential for important credentials
-- **Recovery mechanisms** must balance security with usability
-- **Key management** becomes critical for certificate access
-- **Succession planning** for organizational certificates
-
-### Adoption and Network Effects
-
-Certificate systems become more valuable as adoption grows:
-
-- **Issuer participation** is needed for valuable certificates
-- **Verifier acceptance** determines practical utility
-- **User adoption** creates network effects
-- **Standardization** enables interoperability
-
-### Legal and Regulatory
-
-Integrating with existing legal frameworks requires:
-
-- **Regulatory compliance** with identity verification laws
-- **Legal recognition** of digital certificates
-- **Audit trails** for compliance reporting
-- **Dispute resolution** mechanisms for conflicts
-
-## The Future of Digital Credentials
-
-As certificate-based identity systems mature, we can expect:
-
-### Widespread Adoption
-
-- **Government integration** with official identity documents
-- **Educational institutions** issuing digital diplomas
-- **Professional organizations** moving to digital certifications
-- **Employers** accepting and requiring digital credentials
-
-### Enhanced Privacy
-
-- **Zero-knowledge proofs** becoming standard
-- **Selective disclosure** built into all systems
-- **Privacy-preserving verification** as the default
-- **User control** over all personal data
-
-### Improved User Experience
-
-- **Seamless integration** with daily digital activities
-- **Automated verification** reducing friction
-- **Intelligent recommendations** for credential building
-- **Universal acceptance** across platforms and services
-
-### New Possibilities
-
-- **Micro-credentials** for specific skills and achievements
-- **Dynamic certificates** that update automatically
-- **Composite credentials** combining multiple sources
-- **AI-assisted verification** for complex claims
-
-Understanding these concepts helps developers and users participate in building a more trustworthy, privacy-preserving digital world where identity verification is both secure and user-controlled.
-
-## Related Concepts
-
-- [Decentralized Identity](./decentralized-identity.md) - Overall identity system architecture
-- [Digital Signatures](./signatures.md) - Cryptographic foundations of certificates
-- [Trust Model](./trust-model.md) - Security assumptions and trust relationships
-- [Key Management](./key-management.md) - Managing cryptographic keys for certificates
-
-## Further Reading
-
-- [Identity Management Tutorial](../tutorials/identity-management.md) - Practical certificate implementation
-- [Security Best Practices](../guides/security-best-practices.md) - Secure certificate handling
-- [AuthFetch Tutorial](../tutorials/authfetch-tutorial.md) - Using certificates for authentication

package/docs/concepts/index.md

@@ -1,77 +0,0 @@
-# Concepts
-
-Essential concepts for understanding and using the BSV TypeScript SDK effectively.
-
-## Core Bitcoin Concepts
-
-### [Transaction Structure](./transaction-structure.md)
-
-Understanding Bitcoin transactions, inputs, outputs, and how they work in the SDK.
-
-### [Script Templates](./script-templates.md)
-
-Standard and custom Bitcoin script patterns available in the SDK.
-
-### [Digital Signatures](./signatures.md)
-
-How digital signatures work in Bitcoin and their implementation in the SDK.
-
-### [Transaction Verification](./verification.md)
-
-Understanding how to verify Bitcoin transactions using the SDK.
-
-### [SPV Verification](./spv-verification.md)
-
-Simplified Payment Verification and merkle proof concepts for lightweight clients.
-
-### [Transaction Fees](./fees.md)
-
-How Bitcoin transaction fees work and fee optimization strategies.
-
-## SDK Architecture
-
-### [SDK Design Philosophy](./sdk-philosophy.md)
-
-Core principles: zero dependencies, SPV-first approach, and vendor neutrality.
-
-### [Wallet Integration](./wallet-integration.md)
-
-How the SDK connects with Bitcoin wallets and manages authentication.
-
-### [Chain Tracking](./chain-tracking.md)
-
-Understanding how the SDK interacts with the Bitcoin network for transaction data.
-
-## Data Formats
-
-### [BEEF Format](./beef.md)
-
-Bitcoin Extras Extension Format for efficient transaction data exchange.
-
-### [Transaction Encoding](./transaction-encoding.md)
-
-How transactions are serialized and deserialized in the SDK.
-
-## Identity and Certificates
-
-### [Decentralized Identity](./decentralized-identity.md)
-
-Understanding BSV's decentralized identity system and certificate-based verification.
-
-### [Identity Certificates](./identity-certificates.md)
-
-How cryptographic certificates work for identity claims and verification.
-
-## Security Model
-
-### [Key Management](./key-management.md)
-
-How private keys, public keys, and cryptographic operations work in the SDK.
-
-### [Trust Model](./trust-model.md)
-
-Understanding the security assumptions and trust relationships in SDK applications.
-
----
-
-These concepts provide the foundational knowledge needed to build Bitcoin applications with the BSV TypeScript SDK. For deeper protocol details, refer to the [BSV Skills Center](https://docs.bsvblockchain.org/).