@bsv/sdk 1.6.9 → 1.6.11

package/docs/concepts/identity-certificates.md

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

@@ -0,0 +1,62 @@
+# 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/).

package/docs/concepts/key-management.md

@@ -0,0 +1,176 @@
+# Key Management
+
+Understanding how private keys, public keys, and cryptographic operations work in the BSV TypeScript SDK.
+
+## Cryptographic Keys
+
+Bitcoin uses elliptic curve cryptography (secp256k1) for key management:
+
+```typescript
+import { PrivateKey, PublicKey } from '@bsv/sdk'
+
+// Generate a new private key
+const privateKey = PrivateKey.fromRandom()
+
+// Derive the corresponding public key
+const publicKey = privateKey.toPublicKey()
+```
+
+## Private Keys
+
+Private keys are 256-bit numbers that control Bitcoin funds:
+
+### Generation
+```typescript
+// Secure random generation
+const privKey = PrivateKey.fromRandom()
+
+// From existing data (use carefully)
+const privKey2 = PrivateKey.fromString('hex_string')
+```
+
+### Formats
+```typescript
+// WIF (Wallet Import Format)
+const wif = privateKey.toWif()
+
+// Hex string
+const hex = privateKey.toString()
+
+// DER encoding
+const der = privateKey.toDER()
+```
+
+## Public Keys
+
+Public keys are derived from private keys and can be shared safely:
+
+### Derivation
+```typescript
+// Always derive from private key
+const publicKey = privateKey.toPublicKey()
+
+// Cannot go backwards (public -> private)
+```
+
+### Formats
+```typescript
+// Compressed (33 bytes) - preferred
+const compressed = publicKey.toString()
+
+// Uncompressed (65 bytes) - legacy
+const uncompressed = publicKey.toString(false)
+
+// DER encoding
+const der = publicKey.toDER()
+```
+
+## Digital Signatures
+
+Private keys create signatures that prove ownership:
+
+```typescript
+// Sign a message
+const message = 'Hello Bitcoin'
+const signature = privateKey.sign(message)
+
+// Verify with public key
+const isValid = publicKey.verify(message, signature)
+```
+
+## Key Derivation
+
+The SDK supports hierarchical key derivation:
+
+```typescript
+// Derive child keys (simplified example)
+const childKey = privateKey.deriveChild(0)
+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()
+
+// Bad: Predictable generation
+const badKey = PrivateKey.fromString('1234567890abcdef...')
+
+// Good: Derive public key when needed
+const pubKey = key.toPublicKey()
+
+// Bad: Store private key unnecessarily
+localStorage.setItem('privateKey', key.toString())
+```
+
+## Wallet Integration
+
+In most applications, wallets handle key management:
+
+The `WalletClient` provides high-level key management through wallet integration:
+
+```typescript
+// Wallet manages keys securely
+const wallet = new WalletClient()
+
+// Application doesn't see private keys
+const action = await wallet.createAction({
+  outputs: [/* transaction outputs */]
+})
+```
+
+When using the `WalletClient`, keys are managed by the connected wallet service:
+
+The `WalletClient` approach is recommended for production applications as it provides:
+
+## Key Recovery
+
+Keys can be recovered from various formats:
+
+```typescript
+// From WIF format
+const key1 = PrivateKey.fromWif(wifString)
+
+// From hex string
+const key2 = PrivateKey.fromString(hexString)
+
+// From DER encoding
+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
+- **AES**: Symmetric encryption
+
+## 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
+
+## Testing and Development
+
+For development and testing:
+- Use testnet for experiments
+- Generate new keys for each test
+- Never use mainnet keys in test code
+- Implement proper key rotation
+
+## Next Steps
+
+- Understand [Digital Signatures](./signatures.md) in detail
+- Learn about [Trust Model](./trust-model.md) considerations
+- Explore [Wallet Integration](./wallet-integration.md) patterns

package/docs/concepts/script-templates.md

@@ -0,0 +1,163 @@
+# Script Templates
+
+Standard and custom Bitcoin script patterns available in the BSV TypeScript SDK.
+
+## What are Script Templates?
+
+Script templates provide reusable patterns for Bitcoin transaction locking and unlocking scripts:
+
+```typescript
+import { P2PKH } from '@bsv/sdk'
+
+// Use a standard template
+const template = new P2PKH()
+
+// Create locking script
+const lockingScript = template.lock(publicKeyHash)
+
+// Create unlocking script
+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)
+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)
+const unlock = p2pk.unlock(signature)
+```
+
+### OP_RETURN (Data Storage)
+Store arbitrary data on-chain:
+```typescript
+const opReturn = new OpReturn()
+const lock = opReturn.lock(data)
+// No unlock needed - unspendable output
+```
+
+## Custom Templates
+
+Create your own script templates:
+
+```typescript
+class TimeLockTemplate implements ScriptTemplate {
+  lock(lockTime: number, publicKeyHash: string): Script {
+    return new Script()
+      .writeNumber(lockTime)
+      .writeOpCode(OpCode.OP_CHECKLOCKTIMEVERIFY)
+      .writeOpCode(OpCode.OP_DROP)
+      .writeOpCode(OpCode.OP_DUP)
+      .writeOpCode(OpCode.OP_HASH160)
+      .writeBin(publicKeyHash)
+      .writeOpCode(OpCode.OP_EQUALVERIFY)
+      .writeOpCode(OpCode.OP_CHECKSIG)
+  }
+
+  unlock(signature: string, publicKey: string): Script {
+    return new Script()
+      .writeBin(signature)
+      .writeBin(publicKey)
+  }
+}
+```
+
+## Template Interface
+
+All templates implement the ScriptTemplate interface:
+
+```typescript
+interface ScriptTemplate {
+  lock(...args: any[]): Script
+  unlock(...args: any[]): Script
+  estimateLength?(args: any[]): number
+}
+```
+
+## 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
+
+## Working with Templates
+
+### Transaction Integration
+```typescript
+// Use template in transaction
+const output = {
+  satoshis: 1000,
+  lockingScript: template.lock(publicKeyHash)
+}
+
+const input = {
+  sourceTransaction: prevTx,
+  sourceOutputIndex: 0,
+  unlockingScript: template.unlock(privateKey, signature)
+}
+```
+
+### Fee Estimation
+```typescript
+// Estimate script size for fee calculation
+const estimatedSize = template.estimateLength([publicKeyHash])
+const fee = estimatedSize * feePerByte
+```
+
+## Advanced Patterns
+
+### Multi-Signature
+```typescript
+class MultiSigTemplate implements ScriptTemplate {
+  lock(threshold: number, publicKeys: string[]): Script {
+    // Implementation for m-of-n multisig
+  }
+  
+  unlock(signatures: string[]): Script {
+    // Implementation for signature collection
+  }
+}
+```
+
+### Conditional Scripts
+```typescript
+class ConditionalTemplate implements ScriptTemplate {
+  lock(condition: Script, trueScript: Script, falseScript: Script): Script {
+    // Implementation for IF/ELSE logic
+  }
+}
+```
+
+## Best Practices
+
+- Use standard templates when possible
+- Test custom templates thoroughly
+- Document template parameters clearly
+- Consider script size and complexity
+- Validate inputs before script creation
+
+## Next Steps
+
+- Learn about [Digital Signatures](./signatures.md) for script authorization
+- Understand [Transaction Structure](./transaction-structure.md) integration
+- Explore [Key Management](./key-management.md) for script security