@bsv/sdk 1.6.12 → 1.6.15

package/docs/concepts/identity-certificates.md

@@ -11,12 +11,15 @@ The key difference is that these digital certificates use cryptographic signatur
 ## 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)
@@ -25,32 +28,39 @@ Anyone can then verify:
 ## 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.
+
+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
@@ -60,21 +70,27 @@ These come from recognized organizations with established authority and verifica
 ## 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
@@ -83,21 +99,27 @@ Certificates have limited lifespans for security reasons:
 ## 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
@@ -105,21 +127,27 @@ The same certificate might be highly valuable in one context but irrelevant in a
 ## 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
@@ -128,28 +156,36 @@ You maintain control over your certificates:
 ## 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
@@ -158,24 +194,28 @@ Organizations can manage access more securely:
 ## 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
@@ -184,28 +224,36 @@ Organizations can manage access more securely:
 ## 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
@@ -216,24 +264,28 @@ Integrating with existing legal frameworks requires:
 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

package/docs/concepts/index.md

@@ -5,56 +5,71 @@ Essential concepts for understanding and using the BSV TypeScript SDK effectivel
 ## 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.
 
 ---

package/docs/concepts/key-management.md

@@ -21,6 +21,7 @@ const publicKey = privateKey.toPublicKey()
 Private keys are 256-bit numbers that control Bitcoin funds:
 
 ### Generation
+
 ```typescript
 // Secure random generation
 const privKey = PrivateKey.fromRandom()
@@ -30,6 +31,7 @@ const privKey2 = PrivateKey.fromString('hex_string')
 ```
 
 ### Formats
+
 ```typescript
 // WIF (Wallet Import Format)
 const wif = privateKey.toWif()
@@ -46,6 +48,7 @@ const der = privateKey.toDER()
 Public keys are derived from private keys and can be shared safely:
 
 ### Derivation
+
 ```typescript
 // Always derive from private key
 const publicKey = privateKey.toPublicKey()
@@ -54,6 +57,7 @@ const publicKey = privateKey.toPublicKey()
 ```
 
 ### Formats
+
 ```typescript
 // Compressed (33 bytes) - preferred
 const compressed = publicKey.toString()
@@ -91,12 +95,14 @@ const childPubKey = childKey.toPublicKey()
 ## Security Considerations
 
 ### Private Key Security
+
 - **Never expose**: Private keys should never be logged or transmitted
 - **Secure storage**: Use encrypted storage for private keys
 - **Random generation**: Always use cryptographically secure randomness
 - **Access control**: Limit who can access private key operations
 
 ### Best Practices
+
 ```typescript
 // Good: Generate securely
 const key = PrivateKey.fromRandom()
@@ -149,6 +155,7 @@ const key3 = PrivateKey.fromDER(derBytes)
 ## Cryptographic Operations
 
 The SDK provides secure implementations of:
+
 - **ECDSA**: Digital signature algorithm
 - **ECDH**: Key exchange protocol
 - **Hash Functions**: SHA-256, RIPEMD-160
@@ -157,6 +164,7 @@ The SDK provides secure implementations of:
 ## Memory Management
 
 Sensitive key data should be cleared when no longer needed:
+
 - Use secure memory practices
 - Clear variables containing key data
 - Avoid keeping keys in memory longer than necessary
@@ -164,6 +172,7 @@ Sensitive key data should be cleared when no longer needed:
 ## Testing and Development
 
 For development and testing:
+
 - Use testnet for experiments
 - Generate new keys for each test
 - Never use mainnet keys in test code

package/docs/concepts/script-templates.md

@@ -22,7 +22,9 @@ const unlockingScript = template.unlock(privateKey, signature)
 ## Standard Templates
 
 ### P2PKH (Pay to Public Key Hash)
+
 The most common Bitcoin script pattern:
+
 ```typescript
 const p2pkh = new P2PKH()
 const lock = p2pkh.lock(publicKeyHash)
@@ -30,7 +32,9 @@ const unlock = p2pkh.unlock(privateKey, signature)
 ```
 
 ### P2PK (Pay to Public Key)
+
 Direct payment to a public key:
+
 ```typescript
 const p2pk = new P2PK()
 const lock = p2pk.lock(publicKey)
@@ -38,7 +42,9 @@ const unlock = p2pk.unlock(signature)
 ```
 
 ### OP_RETURN (Data Storage)
+
 Store arbitrary data on-chain:
+
 ```typescript
 const opReturn = new OpReturn()
 const lock = opReturn.lock(data)
@@ -86,16 +92,19 @@ interface ScriptTemplate {
 ## Benefits
 
 ### Reusability
+
 - Standard patterns for common use cases
 - Consistent implementation across applications
 - Reduced development time
 
 ### Security
+
 - Well-tested script patterns
 - Reduced risk of script errors
 - Best practice implementations
 
 ### Maintainability
+
 - Clear separation of script logic
 - Easy to update and modify
 - Testable components
@@ -103,6 +112,7 @@ interface ScriptTemplate {
 ## Working with Templates
 
 ### Transaction Integration
+
 ```typescript
 // Use template in transaction
 const output = {
@@ -118,6 +128,7 @@ const input = {
 ```
 
 ### Fee Estimation
+
 ```typescript
 // Estimate script size for fee calculation
 const estimatedSize = template.estimateLength([publicKeyHash])
@@ -127,6 +138,7 @@ const fee = estimatedSize * feePerByte
 ## Advanced Patterns
 
 ### Multi-Signature
+
 ```typescript
 class MultiSigTemplate implements ScriptTemplate {
   lock(threshold: number, publicKeys: string[]): Script {
@@ -140,6 +152,7 @@ class MultiSigTemplate implements ScriptTemplate {
 ```
 
 ### Conditional Scripts
+
 ```typescript
 class ConditionalTemplate implements ScriptTemplate {
   lock(condition: Script, trueScript: Script, falseScript: Script): Script {

package/docs/concepts/sdk-philosophy.md

@@ -5,6 +5,7 @@ This document details the core principles behind the BSV TypeScript SDK architec
 ## Zero Dependencies
 
 The SDK is built without external dependencies to:
+
 - Minimize security attack surface
 - Reduce bundle size and complexity
 - Ensure long-term stability
@@ -13,6 +14,7 @@ The SDK is built without external dependencies to:
 ## SPV-First Approach
 
 The SDK prioritizes Simplified Payment Verification:
+
 - **Lightweight**: No need to download the full blockchain
 - **Efficient**: Verify transactions using merkle proofs
 - **Scalable**: Works with millions of transactions
@@ -21,6 +23,7 @@ The SDK prioritizes Simplified Payment Verification:
 ## Vendor Neutrality
 
 The SDK works with any compliant Bitcoin infrastructure:
+
 - **Wallet Agnostic**: Supports any BRC-100 compliant wallet
 - **Network Flexible**: Works with different chain tracking services
 - **Service Independent**: No lock-in to specific providers
@@ -28,6 +31,7 @@ The SDK works with any compliant Bitcoin infrastructure:
 ## Modular Design
 
 Components are designed to work independently:
+
 - **Composable**: Mix and match functionality as needed
 - **Extensible**: Easy to add custom implementations
 - **Testable**: Each component can be tested in isolation
@@ -36,6 +40,7 @@ Components are designed to work independently:
 ## TypeScript-First
 
 Built specifically for TypeScript to provide:
+
 - **Type Safety**: Catch errors at compile time
 - **Developer Experience**: Rich IDE support and autocomplete
 - **Documentation**: Types serve as living documentation
@@ -44,6 +49,7 @@ Built specifically for TypeScript to provide:
 ## Security by Design
 
 Security considerations are built into every component:
+
 - **Cryptographic Primitives**: Secure implementations of Bitcoin cryptography
 - **Input Validation**: All inputs are validated and sanitized
 - **Error Handling**: Comprehensive error handling prevents information leakage
@@ -52,6 +58,7 @@ Security considerations are built into every component:
 ## Performance Focused
 
 Optimized for real-world application needs:
+
 - **Memory Efficient**: Minimal memory footprint
 - **Fast Execution**: Optimized critical paths
 - **Batch Processing**: Support for high-throughput scenarios
@@ -60,6 +67,7 @@ Optimized for real-world application needs:
 ## Developer-Friendly
 
 Designed to make Bitcoin development accessible:
+
 - **Clear APIs**: Intuitive method names and parameters
 - **Comprehensive Documentation**: Tutorials, guides, and references
 - **Working Examples**: Real code that developers can use immediately

package/docs/concepts/signatures.md

@@ -22,6 +22,7 @@ const isValid = publicKey.verify(message, signature)
 ## Bitcoin Signatures
 
 Bitcoin uses ECDSA (Elliptic Curve Digital Signature Algorithm):
+
 - **secp256k1**: The elliptic curve used by Bitcoin
 - **SHA-256**: Hash function for message digests
 - **DER Encoding**: Standard format for signature serialization
@@ -31,25 +32,33 @@ Bitcoin uses ECDSA (Elliptic Curve Digital Signature Algorithm):
 SIGHASH flags determine what parts of a transaction are signed:
 
 ### SIGHASH_ALL (Default)
+
 Signs all inputs and outputs:
+
 ```typescript
 const signature = privateKey.sign(txHash, 'all')
 ```
 
 ### SIGHASH_NONE
+
 Signs all inputs but no outputs:
+
 ```typescript
 const signature = privateKey.sign(txHash, 'none')
 ```
 
 ### SIGHASH_SINGLE
+
 Signs all inputs and one corresponding output:
+
 ```typescript
 const signature = privateKey.sign(txHash, 'single')
 ```
 
 ### SIGHASH_ANYONECANPAY
+
 Can be combined with other flags to sign only one input:
+
 ```typescript
 const signature = privateKey.sign(txHash, 'all|anyonecanpay')
 ```
@@ -102,16 +111,19 @@ const s = signature.s
 ## Security Considerations
 
 ### Nonce Security
+
 - Each signature must use a unique, random nonce
 - Reusing nonces can leak private keys
 - The SDK handles nonce generation securely
 
 ### Signature Malleability
+
 - Bitcoin signatures can be modified without invalidating them
 - Use canonical signatures to prevent malleability
 - The SDK produces canonical signatures by default
 
 ### Hash Types
+
 - Choose appropriate SIGHASH types for your use case
 - SIGHASH_ALL is safest for most applications
 - Other types enable advanced transaction patterns
@@ -119,6 +131,7 @@ const s = signature.s
 ## Common Patterns
 
 ### Multi-Input Signing
+
 ```typescript
 // Sign multiple inputs in a transaction
 for (let i = 0; i < transaction.inputs.length; i++) {
@@ -128,6 +141,7 @@ for (let i = 0; i < transaction.inputs.length; i++) {
 ```
 
 ### Conditional Signatures
+
 ```typescript
 // Different signatures for different conditions
 const signature1 = privateKey1.sign(txHash, 'all')
@@ -137,6 +151,7 @@ const signature2 = privateKey2.sign(txHash, 'single')
 ## Error Handling
 
 Common signature issues:
+
 - Invalid private key format
 - Incorrect message hash
 - Malformed signature data