@bsv/sdk 1.6.12 → 1.6.15

package/docs/reference/errors.md

@@ -7,40 +7,48 @@ Complete reference for error codes, messages, and troubleshooting in the BSV Typ
 ### Transaction Errors
 
 #### INSUFFICIENT_FUNDS
+
 **Code**: `INSUFFICIENT_FUNDS`  
 **Message**: "Insufficient funds to create transaction"  
 **Cause**: Wallet doesn't have enough UTXOs to cover transaction outputs and fees  
 **Solutions**:
+
 - Check wallet balance with `listOutputs()`
 - Reduce transaction amount
 - Wait for pending transactions to confirm
 - Use smaller fee rates
 
 #### INVALID_TRANSACTION
+
 **Code**: `INVALID_TRANSACTION`  
 **Message**: "Transaction validation failed"  
 **Cause**: Transaction structure or signatures are invalid  
 **Solutions**:
+
 - Verify all inputs are properly signed
 - Check script templates are correct
 - Ensure transaction format is valid
 - Validate all output amounts are positive
 
 #### TRANSACTION_TOO_LARGE
+
 **Code**: `TRANSACTION_TOO_LARGE`  
 **Message**: "Transaction exceeds maximum size limit"  
 **Cause**: Transaction size exceeds network limits  
 **Solutions**:
+
 - Reduce number of inputs/outputs
 - Use more efficient script templates
 - Split into multiple transactions
 - Optimize data storage methods
 
 #### INVALID_SCRIPT
+
 **Code**: `INVALID_SCRIPT`  
 **Message**: "Script execution failed"  
 **Cause**: Locking or unlocking script contains errors  
 **Solutions**:
+
 - Validate script syntax with `Script.fromASM()`
 - Check opcode usage and limits
 - Verify script template implementation
@@ -49,40 +57,48 @@ Complete reference for error codes, messages, and troubleshooting in the BSV Typ
 ### Wallet Errors
 
 #### WALLET_NOT_CONNECTED
+
 **Code**: `WALLET_NOT_CONNECTED`  
 **Message**: "Wallet connection not established"  
 **Cause**: WalletClient not connected to substrate  
 **Solutions**:
+
 - Call `await wallet.connectToSubstrate()`
 - Check wallet application is running
 - Verify network connectivity
 - Restart wallet application if needed
 
 #### AUTHENTICATION_FAILED
+
 **Code**: `AUTHENTICATION_FAILED`  
 **Message**: "Wallet authentication failed"  
 **Cause**: User denied access or authentication expired  
 **Solutions**:
+
 - Re-authenticate with wallet
 - Check originator domain permissions
 - Verify wallet trust settings
 - Clear cached authentication state
 
 #### WALLET_LOCKED
+
 **Code**: `WALLET_LOCKED`  
 **Message**: "Wallet is locked or requires password"  
 **Cause**: Wallet requires user authentication  
 **Solutions**:
+
 - Unlock wallet application
 - Enter wallet password
 - Check wallet auto-lock settings
 - Verify user session is active
 
 #### ACTION_REJECTED
+
 **Code**: `ACTION_REJECTED`  
 **Message**: "User rejected the transaction"  
 **Cause**: User declined transaction in wallet UI  
 **Solutions**:
+
 - Retry transaction with user consent
 - Adjust transaction parameters
 - Provide clearer transaction description
@@ -91,40 +107,48 @@ Complete reference for error codes, messages, and troubleshooting in the BSV Typ
 ### Network Errors
 
 #### NETWORK_ERROR
+
 **Code**: `NETWORK_ERROR`  
 **Message**: "Network request failed"  
 **Cause**: Connection issues with blockchain nodes  
 **Solutions**:
+
 - Check internet connectivity
 - Verify node endpoints are accessible
 - Try alternative chain trackers
 - Implement retry logic with exponential backoff
 
 #### NODE_UNAVAILABLE
+
 **Code**: `NODE_UNAVAILABLE`  
 **Message**: "Blockchain node is unavailable"  
 **Cause**: Target node is down or unreachable  
 **Solutions**:
+
 - Switch to backup node endpoints
 - Check node status and health
 - Use multiple chain tracker instances
 - Implement failover mechanisms
 
 #### BROADCAST_FAILED
+
 **Code**: `BROADCAST_FAILED`  
 **Message**: "Transaction broadcast failed"  
 **Cause**: Network rejected transaction or broadcast error  
 **Solutions**:
+
 - Verify transaction is valid
 - Check network fees are adequate
 - Retry broadcast after delay
 - Use alternative broadcast endpoints
 
 #### TIMEOUT_ERROR
+
 **Code**: `TIMEOUT_ERROR`  
 **Message**: "Request timeout exceeded"  
 **Cause**: Network request took too long  
 **Solutions**:
+
 - Increase timeout values
 - Check network latency
 - Use faster endpoints
@@ -133,40 +157,48 @@ Complete reference for error codes, messages, and troubleshooting in the BSV Typ
 ### Cryptographic Errors
 
 #### INVALID_PRIVATE_KEY
+
 **Code**: `INVALID_PRIVATE_KEY`  
 **Message**: "Private key is invalid or out of range"  
 **Cause**: Private key doesn't meet secp256k1 requirements  
 **Solutions**:
+
 - Generate new key with `PrivateKey.fromRandom()`
 - Validate key is within curve order
 - Check key format and encoding
 - Use proper key derivation methods
 
 #### INVALID_PUBLIC_KEY
+
 **Code**: `INVALID_PUBLIC_KEY`  
 **Message**: "Public key is invalid or not on curve"  
 **Cause**: Public key point is invalid  
 **Solutions**:
+
 - Verify key derivation from private key
 - Check point coordinates are valid
 - Validate key format (compressed/uncompressed)
 - Use `PublicKey.fromPrivateKey()` for generation
 
 #### SIGNATURE_VERIFICATION_FAILED
+
 **Code**: `SIGNATURE_VERIFICATION_FAILED`  
 **Message**: "Digital signature verification failed"  
 **Cause**: Signature doesn't match message and public key  
 **Solutions**:
+
 - Verify message hash is correct
 - Check signature format (DER encoding)
 - Ensure correct public key is used
 - Validate signature components (r, s values)
 
 #### ENCRYPTION_FAILED
+
 **Code**: `ENCRYPTION_FAILED`  
 **Message**: "Symmetric encryption operation failed"  
 **Cause**: AES encryption/decryption error  
 **Solutions**:
+
 - Verify encryption key is valid
 - Check data format and encoding
 - Ensure proper IV/nonce usage
@@ -175,30 +207,36 @@ Complete reference for error codes, messages, and troubleshooting in the BSV Typ
 ### SPV Verification Errors
 
 #### INVALID_MERKLE_PROOF
+
 **Code**: `INVALID_MERKLE_PROOF`  
 **Message**: "Merkle proof verification failed"  
 **Cause**: Merkle path doesn't lead to valid root  
 **Solutions**:
+
 - Verify merkle path structure
 - Check transaction hash calculation
 - Validate block header merkle root
 - Ensure proof completeness
 
 #### BLOCK_HEADER_INVALID
+
 **Code**: `BLOCK_HEADER_INVALID`  
 **Message**: "Block header validation failed"  
 **Cause**: Block header doesn't meet consensus rules  
 **Solutions**:
+
 - Verify header hash and difficulty
 - Check timestamp validity
 - Validate previous block hash
 - Ensure proper header format
 
 #### CHAIN_VALIDATION_FAILED
+
 **Code**: `CHAIN_VALIDATION_FAILED`  
 **Message**: "Blockchain validation failed"  
 **Cause**: Chain doesn't follow consensus rules  
 **Solutions**:
+
 - Verify chain continuity
 - Check difficulty adjustments
 - Validate block timestamps
@@ -207,20 +245,24 @@ Complete reference for error codes, messages, and troubleshooting in the BSV Typ
 ### Configuration Errors
 
 #### INVALID_CONFIG
+
 **Code**: `INVALID_CONFIG`  
 **Message**: "SDK configuration is invalid"  
 **Cause**: Configuration parameters are incorrect  
 **Solutions**:
+
 - Validate configuration schema
 - Check required parameters are present
 - Verify network settings
 - Use default configuration as baseline
 
 #### UNSUPPORTED_NETWORK
+
 **Code**: `UNSUPPORTED_NETWORK`  
 **Message**: "Network type is not supported"  
 **Cause**: Invalid network specification  
 **Solutions**:
+
 - Use supported networks: mainnet, testnet, regtest
 - Check network configuration
 - Verify chain parameters
@@ -315,9 +357,11 @@ function categorizeError(error: WalletErrorObject): 'user' | 'network' | 'system
 ### Common Issues and Solutions
 
 #### "RPC Error: no header should have returned false"
+
 **Symptoms**: Error during `createAction` calls  
 **Cause**: Wallet input selection issues  
 **Solutions**:
+
 1. Restart wallet application
 2. Ensure wallet is fully synced
 3. Use slightly larger amounts (200-500 satoshis)
@@ -325,27 +369,33 @@ function categorizeError(error: WalletErrorObject): 'user' | 'network' | 'system
 5. Check for sufficient confirmed UTXOs
 
 #### "Insufficient funds" with Available Balance
+
 **Symptoms**: Error despite wallet showing balance  
 **Cause**: UTXOs not properly selected by wallet  
 **Solutions**:
+
 1. Check UTXO status with `listOutputs()`
 2. Verify UTXOs are confirmed
 3. Restart wallet to refresh UTXO cache
 4. Use manual input selection if supported
 
 #### Transaction Broadcast Failures
+
 **Symptoms**: Valid transactions rejected by network  
 **Cause**: Various network or validation issues  
 **Solutions**:
+
 1. Verify transaction format and signatures
 2. Check fee rates are adequate
 3. Ensure inputs are unspent
 4. Try alternative broadcast endpoints
 
 #### Wallet Connection Issues
+
 **Symptoms**: Cannot connect to wallet substrate  
 **Cause**: Wallet not running or permission issues  
 **Solutions**:
+
 1. Ensure wallet application is running
 2. Check originator domain permissions
 3. Clear browser cache and cookies

package/docs/reference/index.md

@@ -5,6 +5,7 @@ Complete technical specifications and API documentation for the BSV TypeScript S
 ## Standards and Interfaces
 
 ### [BRC-100 Wallet Interface](./brc-100.md)
+
 - Unified wallet-to-application interface standard
 - WalletClient implementation details
 - JSON API specifications
@@ -12,26 +13,31 @@ Complete technical specifications and API documentation for the BSV TypeScript S
 ## Core Classes
 
 ### [Transaction Class](./transaction.md)
+
 - Constructor options and methods
 - Input/output management
 - Serialization formats
 
 ### [PrivateKey/PublicKey Classes](./primitives.md)
+
 - Key generation methods
 - Import/export formats
 - Cryptographic operations
 
 ### [Transaction Signatures Reference](./transaction-signatures.md)
+
 - ECDSA signature components
 - DER encoding format
 - Signature hash types (SIGHASH flags)
 
 ### [Script Classes](./script.md)
+
 - Script construction utilities
 - Standard script templates
 - Custom script patterns
 
 ### [OP Codes Reference](./op-codes.md)
+
 - Complete opcode listing and descriptions
 - Opcode categories and usage patterns
 - Script execution examples
@@ -39,17 +45,20 @@ Complete technical specifications and API documentation for the BSV TypeScript S
 ## Module Reference
 
 ### [Primitives Module](./primitives.md)
+
 - Cryptographic primitives
 - Hash functions
 - Security implementation notes
 
 ### [Transaction Module](./transaction.md)
+
 - Transaction lifecycle
 - Fee calculation details
 - Broadcasting options
 - SPV verification
 
 ### [Wallet Module](./wallet.md)
+
 - Wallet architecture patterns
 - Integration guidelines
 - BRC-100 compliance notes
@@ -57,6 +66,7 @@ Complete technical specifications and API documentation for the BSV TypeScript S
 ## Configuration Reference
 
 ### [SDK Configuration Options](./configuration.md)
+
 ```typescript
 interface SDKConfig {
   network: 'mainnet' | 'testnet' | 'regtest'
@@ -67,12 +77,14 @@ interface SDKConfig {
 ```
 
 ### [ARC Configuration](./arc-config.md)
+
 - Endpoint configuration
 - Authentication methods
 - Rate limiting options
 - Failover settings
 
 ### [Network Configuration](./network-config.md)
+
 - Mainnet vs testnet settings
 - Custom network parameters
 - Node endpoint configurations
@@ -80,17 +92,18 @@ interface SDKConfig {
 ## Error Reference
 
 ### [Error Codes and Messages](./errors.md)
+
 - Transaction validation errors
 - Network connectivity errors
 - Cryptographic operation errors
 - Troubleshooting steps
 
 ### [Debugging Guide](./debugging.md)
+
 - SDK logging configuration
 - Debug mode activation
 - Transaction inspection tools
 
-
 ## Swagger
 
 [BRC-100](https://brc.dev/100) defines a Unified, Vendor-Neutral, Unchanging, and Open BSV Blockchain Standard Wallet-to-Application Interface which is implemented in this library within the WalletClient class. The API is laid out here as a swagger openapi document to offer a fast-track to understanding the interface which is implemented across multiple substrates. The JSON api is generally considered a developer friendly introduction to the WalletClient, where an binary equivalent ABI may be preferred for production use cases.

package/docs/reference/op-codes.md

@@ -14,6 +14,7 @@ Bitcoin scripts operate in a **stack-based execution environment** with two prim
 - **Alt Stack**: Provides additional stack flexibility for complex operations
 
 Scripts consist of two parts:
+
 1. **Unlocking Script**: Provided by the spender, supplies data to satisfy locking conditions
 2. **Locking Script**: Defines the conditions that must be met to spend the output
 
@@ -47,6 +48,7 @@ const script = Script.fromASM('OP_DUP OP_HASH160 ' + publicKeyHash + ' OP_EQUALV
 ## Opcode Categories
 
 ### Push Operations
+
 Push data onto the stack:
 
 ```typescript
@@ -63,6 +65,7 @@ OP.OP_PUSHDATA4  // Push up to 4,294,967,295 bytes
 ```
 
 ### Stack Operations
+
 Manipulate stack contents:
 
 ```typescript
@@ -75,6 +78,7 @@ OP.OP_TOALTSTACK // Move item to alt stack
 ```
 
 ### Arithmetic Operations
+
 Perform mathematical operations:
 
 ```typescript
@@ -88,6 +92,7 @@ OP.OP_MAX        // Return maximum of two values
 ```
 
 ### Comparison Operations
+
 Compare values and return boolean results:
 
 ```typescript
@@ -100,6 +105,7 @@ OP.OP_WITHIN        // Check if value is within range
 ```
 
 ### Cryptographic Operations
+
 Perform cryptographic functions:
 
 ```typescript
@@ -112,6 +118,7 @@ OP.OP_CHECKMULTISIG // Verify multiple signatures
 ```
 
 ### Control Flow Operations
+
 Control script execution:
 
 ```typescript
@@ -125,6 +132,7 @@ OP.OP_RETURN     // Mark output as unspendable
 ## Common Script Patterns
 
 ### Pay-to-Public-Key-Hash (P2PKH)
+
 The most common Bitcoin script pattern:
 
 ```typescript
@@ -145,6 +153,7 @@ const p2pkhUnlock = new UnlockingScript([
 ```
 
 ### Data Storage Script
+
 Store arbitrary data on the blockchain:
 
 ```typescript
@@ -156,6 +165,7 @@ const dataScript = new LockingScript([
 ```
 
 ### Multi-Signature Script
+
 Require multiple signatures:
 
 ```typescript
@@ -170,10 +180,10 @@ const multisigScript = new LockingScript([
 ])
 ```
 
-
 ## Security Considerations
 
 ### Disabled Opcodes
+
 Some opcodes are disabled for security reasons:
 
 ```typescript
@@ -187,6 +197,7 @@ OP.OP_VERNOTIF  // Disabled: inverse conditional verification
 ## Best Practices
 
 ### 1. Use Script Templates
+
 Leverage SDK script templates for common patterns:
 
 ```typescript
@@ -198,6 +209,7 @@ const lockingScript = p2pkh.lock(publicKeyHash)
 ```
 
 ### 2. Validate Scripts
+
 Always validate scripts before use:
 
 ```typescript
@@ -210,6 +222,7 @@ try {
 ```
 
 ### 3. Handle Execution Errors
+
 Implement proper error handling:
 
 ```typescript
@@ -228,6 +241,7 @@ try {
 ## Common Use Cases
 
 ### 1. Payment Scripts
+
 Standard payment to public key hash:
 
 ```typescript
@@ -235,6 +249,7 @@ const paymentScript = Script.fromASM(`OP_DUP OP_HASH160 ${pubKeyHash} OP_EQUALVE
 ```
 
 ### 2. Data Storage
+
 Store application data on-chain:
 
 ```typescript
@@ -242,6 +257,7 @@ const dataScript = Script.fromASM(`OP_RETURN ${Buffer.from(jsonData).toString('h
 ```
 
 ### 3. Smart Contracts
+
 Create conditional spending logic:
 
 ```typescript
@@ -256,6 +272,7 @@ const contractScript = Script.fromASM(`
 ```
 
 ### 4. Puzzle Scripts
+
 Create cryptographic puzzles:
 
 ```typescript
@@ -266,6 +283,7 @@ const puzzleScript = Script.fromASM(`OP_HASH256 ${targetHash} OP_EQUAL`)
 ## Debugging Scripts
 
 ### Script Execution Tracing
+
 Monitor script execution step by step:
 
 ```typescript
@@ -284,6 +302,7 @@ while (!spend.isFinished()) {
 ```
 
 ### Common Debugging Patterns
+
 Identify and fix common script issues:
 
 ```typescript

package/docs/reference/transaction-signatures.md

@@ -1,5 +1,6 @@
 # Transaction Signatures Reference
-** SKELETON PLACEHOLDER - check  https://docs.bsvblockchain.org/guides/sdks/ts/low-level/tx_sig ***
+
+** SKELETON PLACEHOLDER - check  <https://docs.bsvblockchain.org/guides/sdks/ts/low-level/tx_sig> ***
 *This is a technical reference document for transaction signatures in the BSV TypeScript SDK.*
 
 ## Introduction

package/docs/reference/transaction.md

@@ -259,6 +259,7 @@ export interface HttpClientRequestOptions<Data = any> {
     method?: string;
     headers?: Record<string, string>;
     data?: Data;
+    signal?: AbortSignal;
 }
 ```
 
@@ -286,6 +287,14 @@ A string to set request's method.
 method?: string
 ```
 
+#### Property signal
+
+An optional AbortSignal to cancel the request, including by explicit timeout.
+
+```ts
+signal?: AbortSignal
+```
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
 ---

package/docs/tutorials/advanced-transaction.md

@@ -2,6 +2,7 @@
 **Prerequisites**: Completed "Transaction Types and Data" tutorial, Node.js, basic TypeScript knowledge  
 
 ## Learning Goals
+
 - Master multi-input/multi-output transaction construction
 - Implement advanced fee calculation and optimization strategies
 - Handle change outputs efficiently
@@ -449,7 +450,6 @@ async function createTransactionChain() {
 createTransactionChain().catch(console.error)
 ```
 
-
 ## Performance Optimization Strategies
 
 For high-throughput applications, consider these optimization techniques:
@@ -546,8 +546,6 @@ async function optimizedTransactionPatterns() {
 optimizedTransactionPatterns().catch(console.error)
 ```
 
-
-
 ## Conclusion
 
 You've now mastered advanced transaction construction with the BSV TypeScript SDK's `WalletClient`. You can:
@@ -567,7 +565,6 @@ These techniques enable you to build production-ready applications that efficien
 
 - Advanced transaction construction requires robust error handling for production applications. For comprehensive coverage of error handling patterns, retry mechanisms, and recovery strategies, see the dedicated [Error Handling Tutorial](./error-handling.md).
 
-
 ## Additional Resources
 
 - [Wallet Reference](../reference/wallet.md)

package/docs/tutorials/aes-encryption.md

@@ -17,6 +17,7 @@
 Advanced Encryption Standard (AES) is a symmetric encryption algorithm where the same key is used for both encryption and decryption. The BSV TypeScript SDK provides the `SymmetricKey` class that implements AES-GCM (Galois/Counter Mode), which provides both confidentiality and authenticity.
 
 AES-GCM offers several advantages:
+
 - **Confidentiality**: Data is encrypted and unreadable without the key
 - **Authenticity**: Built-in authentication prevents tampering
 - **Performance**: Fast encryption/decryption operations
@@ -127,11 +128,13 @@ console.log('SDK decrypted from hex:', sdkDecryptedMessage)
 The `enc` parameter in the SDK's `encrypt()` and `decrypt()` methods can be confusing. Here's how it actually works:
 
 **In `encrypt(data, enc)`:**
+
 - `enc` specifies how to **interpret the input data**
 - `enc: 'hex'` means the input data is a hex string that should be converted to bytes
 - The output format is determined by the `enc` parameter (hex string if `enc: 'hex'`, byte array otherwise)
 
 **In `decrypt(data, enc)`:**
+
 - `enc` specifies the **output format**
 - `enc: 'hex'` returns the decrypted data as a hex string
 - `enc: 'utf8'` returns the decrypted data as a UTF-8 string
@@ -153,7 +156,6 @@ const finalMessage = Buffer.from(decryptedHex, 'hex').toString('utf8')
 console.log('Final message:', finalMessage) // 'Hello, World!'
 ```
 
-
 ## Complete Encryption Example
 
 Here's a comprehensive example demonstrating the full encryption workflow: