@bsv/sdk 1.6.9 → 1.6.11

package/docs/reference/op-codes.md

@@ -0,0 +1,306 @@
+# OP Codes
+
+*Understanding Bitcoin script opcodes and their usage in the BSV TypeScript SDK.*
+
+## What are OP Codes?
+
+OP codes (operation codes) are the fundamental building blocks of Bitcoin's scripting language. They are operational instructions that manipulate data on the script execution stack to define the conditions under which Bitcoin can be spent. Each opcode performs a specific function such as arithmetic operations, logical comparisons, cryptographic operations, or stack manipulation.
+
+## Script Execution Environment
+
+Bitcoin scripts operate in a **stack-based execution environment** with two primary data structures:
+
+- **Main Stack**: Where most operations are performed
+- **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
+
+The execution begins with the unlocking script placing data on the stack, followed by the locking script operating on the same stack. A spend is valid if the top of the stack contains a "true" value (non-zero) after execution.
+
+## SDK Integration
+
+The BSV TypeScript SDK provides comprehensive opcode support through the `OP` object and script execution engine:
+
+```typescript
+import { OP, Script, LockingScript, UnlockingScript } from '@bsv/sdk'
+
+// Access opcodes by name
+console.log(OP.OP_DUP)        // 0x76
+console.log(OP.OP_HASH160)    // 0xa9
+console.log(OP.OP_CHECKSIG)   // 0xac
+
+// Create scripts using opcodes
+const lockingScript = new LockingScript([
+  { op: OP.OP_DUP },
+  { op: OP.OP_HASH160 },
+  { op: 20, data: publicKeyHash }, // Push 20 bytes
+  { op: OP.OP_EQUALVERIFY },
+  { op: OP.OP_CHECKSIG }
+])
+
+// Create from ASM (Assembly) format
+const script = Script.fromASM('OP_DUP OP_HASH160 ' + publicKeyHash + ' OP_EQUALVERIFY OP_CHECKSIG')
+```
+
+## Opcode Categories
+
+### Push Operations
+Push data onto the stack:
+
+```typescript
+// Push small numbers (0-16)
+OP.OP_0        // Push empty array (false)
+OP.OP_1        // Push number 1 (true)
+OP.OP_2        // Push number 2
+// ... up to OP_16
+
+// Push data of various sizes
+OP.OP_PUSHDATA1  // Push up to 255 bytes
+OP.OP_PUSHDATA2  // Push up to 65,535 bytes  
+OP.OP_PUSHDATA4  // Push up to 4,294,967,295 bytes
+```
+
+### Stack Operations
+Manipulate stack contents:
+
+```typescript
+OP.OP_DUP        // Duplicate top stack item
+OP.OP_DROP       // Remove top stack item
+OP.OP_SWAP       // Swap top two stack items
+OP.OP_ROT        // Rotate top three stack items
+OP.OP_2DUP       // Duplicate top two stack items
+OP.OP_TOALTSTACK // Move item to alt stack
+```
+
+### Arithmetic Operations
+Perform mathematical operations:
+
+```typescript
+OP.OP_ADD        // Add top two stack items
+OP.OP_SUB        // Subtract second from top
+OP.OP_MUL        // Multiply top two items
+OP.OP_DIV        // Divide second by top
+OP.OP_MOD        // Modulo operation
+OP.OP_MIN        // Return minimum of two values
+OP.OP_MAX        // Return maximum of two values
+```
+
+### Comparison Operations
+Compare values and return boolean results:
+
+```typescript
+OP.OP_EQUAL         // Check if top two items are equal
+OP.OP_EQUALVERIFY   // Equal check + verify (fail if false)
+OP.OP_NUMEQUAL      // Numeric equality check
+OP.OP_LESSTHAN      // Check if second < top
+OP.OP_GREATERTHAN   // Check if second > top
+OP.OP_WITHIN        // Check if value is within range
+```
+
+### Cryptographic Operations
+Perform cryptographic functions:
+
+```typescript
+OP.OP_SHA1          // SHA-1 hash
+OP.OP_SHA256        // SHA-256 hash
+OP.OP_HASH160       // RIPEMD160(SHA256(x))
+OP.OP_HASH256       // SHA256(SHA256(x))
+OP.OP_CHECKSIG      // Verify signature
+OP.OP_CHECKMULTISIG // Verify multiple signatures
+```
+
+### Control Flow Operations
+Control script execution:
+
+```typescript
+OP.OP_IF         // Conditional execution
+OP.OP_ELSE       // Alternative branch
+OP.OP_ENDIF      // End conditional
+OP.OP_VERIFY     // Fail if top stack item is false
+OP.OP_RETURN     // Mark output as unspendable
+```
+
+## Common Script Patterns
+
+### Pay-to-Public-Key-Hash (P2PKH)
+The most common Bitcoin script pattern:
+
+```typescript
+// Locking script: OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
+const p2pkhLock = new LockingScript([
+  { op: OP.OP_DUP },
+  { op: OP.OP_HASH160 },
+  { op: 20, data: publicKeyHash },
+  { op: OP.OP_EQUALVERIFY },
+  { op: OP.OP_CHECKSIG }
+])
+
+// Unlocking script: <signature> <publicKey>
+const p2pkhUnlock = new UnlockingScript([
+  { op: signature.length, data: signature },
+  { op: publicKey.length, data: publicKey }
+])
+```
+
+### Data Storage Script
+Store arbitrary data on the blockchain:
+
+```typescript
+// OP_RETURN <data>
+const dataScript = new LockingScript([
+  { op: OP.OP_RETURN },
+  { op: data.length, data: data }
+])
+```
+
+### Multi-Signature Script
+Require multiple signatures:
+
+```typescript
+// 2-of-3 multisig: OP_2 <pubKey1> <pubKey2> <pubKey3> OP_3 OP_CHECKMULTISIG
+const multisigScript = new LockingScript([
+  { op: OP.OP_2 },
+  { op: pubKey1.length, data: pubKey1 },
+  { op: pubKey2.length, data: pubKey2 },
+  { op: pubKey3.length, data: pubKey3 },
+  { op: OP.OP_3 },
+  { op: OP.OP_CHECKMULTISIG }
+])
+```
+
+
+## Security Considerations
+
+### Disabled Opcodes
+Some opcodes are disabled for security reasons:
+
+```typescript
+// These opcodes will cause script failure
+OP.OP_2MUL      // Disabled: multiply by 2
+OP.OP_2DIV      // Disabled: divide by 2  
+OP.OP_VERIF     // Disabled: conditional verification
+OP.OP_VERNOTIF  // Disabled: inverse conditional verification
+```
+
+## Best Practices
+
+### 1. Use Script Templates
+Leverage SDK script templates for common patterns:
+
+```typescript
+import { P2PKH, MultiSig, RPuzzle } from '@bsv/sdk'
+
+// Use templates instead of manual opcode construction
+const p2pkh = new P2PKH()
+const lockingScript = p2pkh.lock(publicKeyHash)
+```
+
+### 2. Validate Scripts
+Always validate scripts before use:
+
+```typescript
+try {
+  const script = Script.fromASM(asmString)
+  // Script is valid
+} catch (error) {
+  console.error('Invalid script:', error.message)
+}
+```
+
+### 3. Handle Execution Errors
+Implement proper error handling:
+
+```typescript
+const spend = new Spend(params)
+try {
+  while (!spend.isFinished()) {
+    if (!spend.step()) {
+      throw new Error(`Script execution failed: ${spend.getDebugString()}`)
+    }
+  }
+} catch (error) {
+  console.error('Script execution error:', error.message)
+}
+```
+
+## Common Use Cases
+
+### 1. Payment Scripts
+Standard payment to public key hash:
+
+```typescript
+const paymentScript = Script.fromASM(`OP_DUP OP_HASH160 ${pubKeyHash} OP_EQUALVERIFY OP_CHECKSIG`)
+```
+
+### 2. Data Storage
+Store application data on-chain:
+
+```typescript
+const dataScript = Script.fromASM(`OP_RETURN ${Buffer.from(jsonData).toString('hex')}`)
+```
+
+### 3. Smart Contracts
+Create conditional spending logic:
+
+```typescript
+const contractScript = Script.fromASM(`
+  OP_IF
+    ${timelock} OP_CHECKLOCKTIMEVERIFY OP_DROP
+    OP_DUP OP_HASH160 ${ownerHash} OP_EQUALVERIFY OP_CHECKSIG
+  OP_ELSE
+    OP_DUP OP_HASH160 ${beneficiaryHash} OP_EQUALVERIFY OP_CHECKSIG
+  OP_ENDIF
+`)
+```
+
+### 4. Puzzle Scripts
+Create cryptographic puzzles:
+
+```typescript
+// Hash puzzle: provide preimage to unlock
+const puzzleScript = Script.fromASM(`OP_HASH256 ${targetHash} OP_EQUAL`)
+```
+
+## Debugging Scripts
+
+### Script Execution Tracing
+Monitor script execution step by step:
+
+```typescript
+const spend = new Spend(params)
+console.log('Initial stack:', spend.getDebugString())
+
+while (!spend.isFinished()) {
+  const success = spend.step()
+  console.log('After step:', spend.getDebugString())
+  
+  if (!success) {
+    console.log('Execution failed at:', spend.getCurrentOpcode())
+    break
+  }
+}
+```
+
+### Common Debugging Patterns
+Identify and fix common script issues:
+
+```typescript
+// Check stack state
+if (spend.getStackSize() === 0) {
+  console.log('Stack is empty - missing data?')
+}
+
+// Check for script errors
+if (spend.hasError()) {
+  console.log('Script error:', spend.getErrorMessage())
+}
+
+// Verify final state
+if (spend.isSuccess() && spend.getStackTop() !== 1) {
+  console.log('Script succeeded but top stack value is not true')
+}
+```
+
+Understanding OP codes enables you to create sophisticated Bitcoin applications with custom spending conditions, smart contracts, and advanced cryptographic protocols using the BSV TypeScript SDK.

package/docs/reference/transaction-signatures.md

@@ -0,0 +1,94 @@
+# Transaction Signatures Reference
+** 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
+
+This reference document provides detailed technical information about transaction signatures in Bitcoin SV and how they are implemented in the TypeScript SDK. It complements the [Key Management and Cryptography tutorial](../tutorials/key-management.md) and the [Advanced Transaction Signing guide](../guides/advanced-transaction-signing.md).
+
+## Signature Components
+
+### ECDSA Signatures
+
+Bitcoin uses the Elliptic Curve Digital Signature Algorithm (ECDSA) with the secp256k1 curve. Each signature consists of two components:
+
+- `r`: A value derived from a random nonce used during signing
+- `s`: A value that combines the private key, message hash, and the nonce
+
+```typescript
+// Structure of a Signature class instance
+class Signature {
+  r: BigNumber; // The r component
+  s: BigNumber; // The s component
+  
+  // Methods for serialization
+  toDER(encoding?: 'hex'): number[] | string;
+  
+  // Static methods for deserialization
+  static fromDER(bytes: number[]): Signature;
+  // Additional methods...
+}
+```
+
+### DER Encoding
+
+Signatures in Bitcoin are encoded using the Distinguished Encoding Rules (DER) format, which provides a standardized way to represent the ECDSA signature components.
+
+## Signature Hash (SIGHASH) Types
+
+Bitcoin transactions use SIGHASH flags to indicate which parts of a transaction are included in the signature hash:
+
+| Flag | Hex Value | Description |
+|------|-----------|-------------|
+| SIGHASH_ALL | 0x01 | Signs all inputs and outputs (default) |
+| SIGHASH_NONE | 0x02 | Signs inputs only, allows any outputs |
+| SIGHASH_SINGLE | 0x03 | Signs inputs and the output with the same index |
+| SIGHASH_ANYONECANPAY | 0x80 | Can be combined with above flags, allows additional inputs |
+
+## Transaction Signature Verification Process
+
+1. Extract signature and public key from the unlockingScript
+2. Determine the SIGHASH flag from the signature
+3. Recreate the signature hash based on the SIGHASH flag
+4. Verify the signature against the hash using the public key
+
+## API Reference
+
+### PrivateKey Methods
+
+```typescript
+// Sign a message or transaction with a private key
+sign(message: string | number[], sigHashType?: number): Promise<Signature>;
+```
+
+### PublicKey Methods
+
+```typescript
+// Verify a signature with a public key
+verify(message: string | number[], signature: Signature): boolean;
+```
+
+### Transaction Methods
+
+```typescript
+// Sign a transaction
+sign(sigHashType?: number): Promise<void>;
+
+// Verify all signatures in a transaction
+verify(): Promise<boolean>;
+```
+
+## Example Implementation Details
+
+```typescript
+// Example of how signature hashing is implemented
+function calculateSignatureHash(tx: Transaction, inputIndex: number, sigHashType: number): number[] {
+  // Implementation details...
+}
+```
+
+## Related Resources
+
+- [Advanced Transaction Signing guide](../guides/advanced-transaction-signing.md)
+- [Key Management and Cryptography tutorial](../tutorials/key-management.md)
+- [Bitcoin Transaction Format](https://reference.cash/protocol/blockchain/transaction)

package/docs/requirements.txt

@@ -0,0 +1,3 @@
+mkdocs>=1.6.0
+mkdocs-material>=9.6.0
+mkdocs-minify-plugin>=0.8.0