@smartledger/bsv 3.1.1 → 3.2.0

package/docs/CUSTOM_SCRIPT_DEVELOPMENT.md

@@ -0,0 +1,320 @@
+# Custom Script Development Guide - SmartLedger-BSV v3.0.2
+
+## Overview
+
+SmartLedger-BSV v3.0.2 provides complete signature capabilities for custom locking and unlocking scripts, enabling developers to build:
+
+- **Custom Payment Conditions** - Beyond standard P2PKH
+- **Multi-Signature Scripts** - Custom m-of-n signatures
+- **Conditional Scripts** - IF/ELSE logic in Bitcoin Script
+- **Time-Locked Scripts** - Block height and timestamp locks
+- **Covenant Scripts** - Scripts that constrain future transactions
+- **Smart Contracts** - Complex business logic on BSV blockchain
+
+## Core API: Manual Signature Creation
+
+For any custom script, use the universal signature creation method:
+
+```javascript
+const bsv = require('smartledger-bsv');
+
+function createCustomSignature(transaction, privateKey, inputIndex, lockingScript, satoshis, sighashType = null) {
+  sighashType = sighashType || (bsv.crypto.Signature.SIGHASH_ALL | bsv.crypto.Signature.SIGHASH_FORKID);
+  
+  const signature = bsv.Transaction.sighash.sign(
+    transaction,
+    privateKey,
+    sighashType,
+    inputIndex,
+    lockingScript,
+    new bsv.crypto.BN(satoshis)
+  );
+  
+  // Return signature with sighash type appended (required for script validation)
+  return Buffer.concat([signature.toDER(), Buffer.from([sighashType])]);
+}
+```
+
+## 1. Multi-Signature Scripts
+
+Create custom m-of-n multi-signature scripts:
+
+```javascript
+// Create 2-of-3 multisig locking script
+const lockingScript = new bsv.Script()
+  .add(bsv.Opcode.OP_2)
+  .add(publicKey1.toBuffer())
+  .add(publicKey2.toBuffer())
+  .add(publicKey3.toBuffer())
+  .add(bsv.Opcode.OP_3)
+  .add(bsv.Opcode.OP_CHECKMULTISIG);
+
+// Create signatures for unlocking
+const sig1 = createCustomSignature(tx, privateKey1, 0, lockingScript, satoshis);
+const sig2 = createCustomSignature(tx, privateKey2, 0, lockingScript, satoshis);
+
+// Create unlocking script (need OP_0 due to CHECKMULTISIG bug)
+const unlockingScript = new bsv.Script()
+  .add(bsv.Opcode.OP_0)
+  .add(sig1)
+  .add(sig2);
+
+tx.inputs[0].setScript(unlockingScript);
+```
+
+## 2. Conditional Scripts (IF/ELSE)
+
+Create scripts with branching logic:
+
+```javascript
+// Locking script: IF <condition1> ELSE <condition2> ENDIF
+const lockingScript = new bsv.Script()
+  .add(bsv.Opcode.OP_IF)
+    // First condition (e.g., key1)
+    .add(bsv.Opcode.OP_DUP)
+    .add(bsv.Opcode.OP_HASH160)
+    .add(publicKey1.toAddress().hashBuffer)
+    .add(bsv.Opcode.OP_EQUALVERIFY)
+    .add(bsv.Opcode.OP_CHECKSIG)
+  .add(bsv.Opcode.OP_ELSE)
+    // Second condition (e.g., key2)
+    .add(bsv.Opcode.OP_DUP)
+    .add(bsv.Opcode.OP_HASH160)
+    .add(publicKey2.toAddress().hashBuffer)
+    .add(bsv.Opcode.OP_EQUALVERIFY)
+    .add(bsv.Opcode.OP_CHECKSIG)
+  .add(bsv.Opcode.OP_ENDIF);
+
+// Unlocking for IF branch
+const unlockingScript = new bsv.Script()
+  .add(signature)
+  .add(publicKey1.toBuffer())
+  .add(bsv.Opcode.OP_1); // Choose IF branch
+
+// Unlocking for ELSE branch
+const unlockingScript = new bsv.Script()
+  .add(signature)
+  .add(publicKey2.toBuffer())
+  .add(bsv.Opcode.OP_0); // Choose ELSE branch
+```
+
+## 3. Time-Locked Scripts
+
+Create scripts that can only be spent after a specific time or block height:
+
+```javascript
+const lockHeight = 700000; // Block height
+
+// Time-locked locking script
+const lockingScript = new bsv.Script()
+  .add(Buffer.from(lockHeight.toString(16).padStart(8, '0'), 'hex').reverse())
+  .add(bsv.Opcode.OP_CHECKLOCKTIMEVERIFY)
+  .add(bsv.Opcode.OP_DROP)
+  // Then normal P2PKH
+  .add(bsv.Opcode.OP_DUP)
+  .add(bsv.Opcode.OP_HASH160)
+  .add(publicKey.toAddress().hashBuffer)
+  .add(bsv.Opcode.OP_EQUALVERIFY)
+  .add(bsv.Opcode.OP_CHECKSIG);
+
+// Set transaction lock time
+const tx = new bsv.Transaction()
+  .from(utxo)
+  .to(address, amount)
+  .lockUntilBlockHeight(lockHeight);
+
+// Create signature and unlocking script normally
+const signature = createCustomSignature(tx, privateKey, 0, lockingScript, satoshis);
+const unlockingScript = new bsv.Script()
+  .add(signature)
+  .add(publicKey.toBuffer());
+```
+
+## 4. Covenant Scripts (Transaction Introspection)
+
+Create scripts that examine the transaction they're in:
+
+```javascript
+// Get transaction preimage for covenant validation
+const sighashType = bsv.crypto.Signature.SIGHASH_ALL | bsv.crypto.Signature.SIGHASH_FORKID;
+const preimage = bsv.Transaction.sighash.sighash(
+  transaction,
+  sighashType,
+  inputIndex,
+  lockingScript,
+  new bsv.crypto.BN(satoshis)
+);
+
+// The preimage contains all transaction data that can be examined:
+// - Version (4 bytes)
+// - Input prevouts hash (32 bytes)
+// - Input sequence hash (32 bytes)
+// - Previous output (36 bytes)
+// - Previous output script (variable)
+// - Previous output amount (8 bytes)
+// - Sequence (4 bytes)
+// - Outputs hash (32 bytes)
+// - Lock time (4 bytes)
+// - Sighash type (4 bytes)
+
+console.log(`Preimage: ${preimage.toString('hex')}`);
+console.log(`Preimage length: ${preimage.length} bytes`);
+```
+
+## 5. Advanced Pattern: State Machine Scripts
+
+Create scripts that enforce state transitions:
+
+```javascript
+// State machine: INIT -> PENDING -> COMPLETE
+const STATE_INIT = 0;
+const STATE_PENDING = 1;
+const STATE_COMPLETE = 2;
+
+function createStateMachineScript(currentState, nextState, publicKeys) {
+  return new bsv.Script()
+    // Check current state
+    .add(Buffer.from([currentState]))
+    .add(bsv.Opcode.OP_EQUAL)
+    .add(bsv.Opcode.OP_VERIFY)
+    
+    // Check next state transition is valid
+    .add(Buffer.from([nextState]))
+    .add(Buffer.from([currentState + 1]))
+    .add(bsv.Opcode.OP_EQUAL)
+    .add(bsv.Opcode.OP_VERIFY)
+    
+    // Require signature
+    .add(bsv.Opcode.OP_DUP)
+    .add(bsv.Opcode.OP_HASH160)
+    .add(publicKeys[currentState].toAddress().hashBuffer)
+    .add(bsv.Opcode.OP_EQUALVERIFY)
+    .add(bsv.Opcode.OP_CHECKSIG);
+}
+```
+
+## 6. Best Practices
+
+### Signature Types
+- Use `SIGHASH_ALL | SIGHASH_FORKID` for most cases (signs entire transaction)
+- Use `SIGHASH_SINGLE | SIGHASH_FORKID` to sign only corresponding output
+- Use `SIGHASH_NONE | SIGHASH_FORKID` to allow output modifications
+
+### Script Validation
+Always test your scripts:
+
+```javascript
+// Verify transaction is valid
+const isValid = transaction.verify();
+console.log(`Transaction valid: ${isValid}`);
+
+// Check specific input signature
+const interpreter = new bsv.Script.Interpreter();
+const isScriptValid = interpreter.verify(
+  unlockingScript,
+  lockingScript,
+  transaction,
+  inputIndex,
+  flags
+);
+```
+
+### Security Considerations
+1. **Always validate inputs** - Check all data before using in scripts
+2. **Use proper sighash types** - Don't accidentally allow transaction modifications
+3. **Test edge cases** - Empty stacks, invalid signatures, malformed scripts
+4. **Minimize script size** - Smaller scripts = lower fees
+5. **Use OP_CHECKLOCKTIMEVERIFY properly** - Ensure nlocktime is set correctly
+
+## 7. Testing Framework
+
+Use our comprehensive test suite:
+
+```bash
+# Run all custom script tests
+node custom_script_signature_test.js
+
+# Test specific patterns
+node covenant_test.js
+node multisig_test.js
+node timelock_test.js
+```
+
+## 8. Ultra-Low Fee Configuration
+
+All custom scripts benefit from our ultra-low fee system:
+
+```javascript
+// Configure ultra-low fees (0.01 sats/byte)
+const feePerKb = 10; // 10 sats per KB = 0.01 sats per byte
+
+const tx = new bsv.Transaction()
+  .from(utxos)
+  .to(address, amount)
+  .feePerKb(feePerKb);
+
+// Custom script transaction will use minimal fees
+console.log(`Transaction fee: ${tx.getFee()} satoshis`);
+```
+
+## 9. Real-World Examples
+
+### Escrow Contract
+```javascript
+// 2-of-3 escrow: buyer, seller, arbitrator
+const escrowScript = new bsv.Script()
+  .add(bsv.Opcode.OP_2)
+  .add(buyerPubKey.toBuffer())
+  .add(sellerPubKey.toBuffer())
+  .add(arbitratorPubKey.toBuffer())
+  .add(bsv.Opcode.OP_3)
+  .add(bsv.Opcode.OP_CHECKMULTISIG);
+```
+
+### Payment Channel
+```javascript
+// Payment channel with time lock fallback
+const channelScript = new bsv.Script()
+  .add(bsv.Opcode.OP_IF)
+    // Both parties agree
+    .add(bsv.Opcode.OP_2)
+    .add(alicePubKey.toBuffer())
+    .add(bobPubKey.toBuffer())
+    .add(bsv.Opcode.OP_2)
+    .add(bsv.Opcode.OP_CHECKMULTISIG)
+  .add(bsv.Opcode.OP_ELSE)
+    // Time lock fallback to Alice
+    .add(Buffer.from(lockTime.toString(16).padStart(8, '0'), 'hex').reverse())
+    .add(bsv.Opcode.OP_CHECKLOCKTIMEVERIFY)
+    .add(bsv.Opcode.OP_DROP)
+    .add(alicePubKey.toBuffer())
+    .add(bsv.Opcode.OP_CHECKSIG)
+  .add(bsv.Opcode.OP_ENDIF);
+```
+
+### Token Contract
+```javascript
+// Simple token transfer covenant
+const tokenScript = new bsv.Script()
+  // Check output preserves token amount
+  .add(bsv.Opcode.OP_DUP)
+  .add(bsv.Opcode.OP_HASH160)
+  .add(newOwnerPubKeyHash)
+  .add(bsv.Opcode.OP_EQUALVERIFY)
+  .add(bsv.Opcode.OP_CHECKSIG)
+  
+  // Covenant: ensure output amount >= input amount
+  .add(bsv.Opcode.OP_DUP)
+  .add(Buffer.from(inputAmount.toString(16), 'hex'))
+  .add(bsv.Opcode.OP_GREATERTHANOREQUAL)
+  .add(bsv.Opcode.OP_VERIFY);
+```
+
+## Support
+
+For custom script development support:
+- Check `custom_script_signature_test.js` for working examples
+- Review `transaction_signature_api_gap.js` for signature troubleshooting
+- All signature methods are battle-tested and production-ready
+
+**SmartLedger-BSV v3.0.2 enables the full power of Bitcoin Script for your applications!** 🚀

package/docs/README.md

@@ -0,0 +1,201 @@
+# SmartLedger-BSV Documentation
+
+Comprehensive documentation for SmartLedger-BSV v3.1.1+ - Advanced Bitcoin SV Library with Enterprise Covenant Framework.
+
+## 📚 Documentation Structure
+
+### Core Guides
+- **[Getting Started](getting-started.md)** - Installation, setup, and first steps
+- **[API Reference](api-reference.md)** - Complete API documentation
+- **[Configuration Guide](configuration.md)** - Setup and optimization
+
+### Advanced Features
+- **[Advanced Covenant Development](ADVANCED_COVENANT_DEVELOPMENT.md)** - BIP143 + nChain PUSHTX techniques
+- **[Custom Script Development](CUSTOM_SCRIPT_DEVELOPMENT.md)** - Script creation patterns
+- **[Covenant Development Resolved](COVENANT_DEVELOPMENT_RESOLVED.md)** - Problem solutions and working examples
+
+### Technical Specifications
+- **[BIP143 Preimage Format](preimage.md)** - Detailed preimage structure specification
+- **[nChain PUSHTX Paper](nchain.md)** - Academic research integration (WP1605)
+- **[Security Best Practices](security-best-practices.md)** - Production guidelines
+
+## 🎯 Quick Navigation
+
+### New to SmartLedger-BSV?
+1. **[Getting Started](getting-started.md)** - Begin here for installation and basic usage
+2. **[Examples Directory](../examples/)** - Hands-on code examples
+3. **[Basic Usage](#basic-usage)** - Common patterns and workflows
+
+### Building Custom Scripts?
+1. **[Custom Script Development](CUSTOM_SCRIPT_DEVELOPMENT.md)** - Complete guide to script creation
+2. **[Script Examples](../examples/scripts/)** - Working code examples
+3. **[API Reference](api-reference.md)** - CustomScriptHelper documentation
+
+### Developing Covenants?
+1. **[Advanced Covenant Development](ADVANCED_COVENANT_DEVELOPMENT.md)** - Complete covenant framework
+2. **[Covenant Examples](../examples/covenants/)** - Working covenant patterns  
+3. **[BIP143 Specification](preimage.md)** - Preimage structure details
+4. **[nChain PUSHTX](nchain.md)** - Academic research foundation
+
+### Production Deployment?
+1. **[Security Best Practices](security-best-practices.md)** - Production guidelines
+2. **[Configuration Guide](configuration.md)** - Optimization and setup
+3. **[API Reference](api-reference.md)** - Complete API documentation
+
+## 🚀 Key Features Overview
+
+### Core Library Capabilities
+- **Complete BSV API**: Full compatibility with Bitcoin SV operations
+- **Ultra-Low Fees**: 0.01 sats/byte configuration (91% fee reduction)  
+- **UTXO Management**: Advanced state management with change outputs
+- **CDN Distribution**: Multiple webpack bundles for web development
+- **Security Hardened**: Enhanced elliptic curve security fixes
+
+### Advanced Covenant Framework
+- **BIP143 Compliant**: Complete preimage parsing with field-by-field access
+- **PUSHTX Integration**: nChain WP1605 in-script signature generation
+- **PELS Support**: Perpetually Enforcing Locking Scripts for ongoing rules
+- **Dual-Level API**: High-level abstractions with granular BSV control
+- **Production Ready**: Comprehensive validation and error handling
+
+### Custom Script Development
+- **Multi-signature Scripts**: Advanced m-of-n signature schemes
+- **Timelock Contracts**: Block height and timestamp constraints
+- **Conditional Logic**: Complex branching and validation rules
+- **Template System**: Pre-built patterns for common use cases
+- **Developer API**: Simplified interface for rapid development
+
+## 📖 Documentation Categories
+
+### 📦 Installation & Setup
+```javascript
+// NPM installation
+npm install @smartledger/bsv
+
+// Basic usage
+const bsv = require('@smartledger/bsv');
+const tx = new bsv.Transaction()
+  .from(utxo)
+  .to(address, amount)
+  .feePerKb(10); // Ultra-low fees
+```
+
+### 🔒 Covenant Development
+```javascript
+// Advanced covenant creation
+const { CovenantInterface } = require('@smartledger/bsv/lib/covenant-interface');
+const covenant = new CovenantInterface();
+
+// PUSHTX covenant with nChain techniques
+const pushtx = covenant.createAdvancedCovenant('pushtx', {
+  publicKey: publicKey,
+  enforceOutputs: true
+});
+
+// Perpetual covenant (PELS)
+const pels = covenant.createAdvancedCovenant('perpetual', {
+  publicKeyHash: pubkeyHash,
+  feeDeduction: 512,
+  enforceScript: true
+});
+```
+
+### 🛠️ Custom Scripts
+```javascript
+// Custom script development
+const { CustomScriptHelper } = require('@smartledger/bsv/lib/custom-script-helper');
+const helper = new CustomScriptHelper();
+
+// Multi-signature script
+const multisig = helper.createMultisigScript([pk1, pk2, pk3], 2);
+
+// Timelock script  
+const timelock = helper.createTimelockScript(publicKey, 750000, 'block');
+```
+
+### 📊 BIP143 Preimage Analysis
+```javascript
+// Enhanced preimage parsing
+const { CovenantPreimage } = require('@smartledger/bsv/lib/covenant-interface');
+const preimage = new CovenantPreimage(preimageHex);
+
+console.log('Version:', preimage.nVersionValue);    // uint32 accessor
+console.log('Amount:', preimage.amountValue);       // BigInt accessor
+console.log('Valid:', preimage.isValid);            // Structure validation
+```
+
+## 🔧 Technical Specifications
+
+### BIP143 Preimage Structure (108+ bytes)
+```
+Field 1:  nVersion        (4 bytes, little-endian)
+Field 2:  hashPrevouts    (32 bytes) - double SHA256 of input outpoints
+Field 3:  hashSequence    (32 bytes) - double SHA256 of input sequences  
+Field 4:  outpoint        (36 bytes) - prevTxId + outputIndex
+Field 5:  scriptCode      (variable) - with varint length encoding
+Field 6:  amount          (8 bytes, little-endian) - UTXO value
+Field 7:  nSequence       (4 bytes, little-endian)
+Field 8:  hashOutputs     (32 bytes) - double SHA256 of all outputs
+Field 9:  nLockTime       (4 bytes, little-endian)
+Field 10: sighashType     (4 bytes, little-endian)
+```
+
+### nChain PUSHTX Techniques (WP1605)
+- **In-script signature generation**: `s = z + Gx mod n`
+- **Generator optimization**: k=a=1 for efficiency
+- **DER canonicalization**: s ≤ n/2 prevents malleability
+- **Message construction**: BIP143 preimage building
+- **Security proof**: Computationally infeasible to forge
+
+## 🔐 Security Considerations
+
+### Critical Security Features
+- **Parameter Fixing**: Public key, ephemeral key, sighash flag must be fixed
+- **DER Canonicalization**: Prevents transaction malleability
+- **Preimage Validation**: Complete BIP143 structure verification
+- **Error Handling**: Comprehensive validation and reporting
+
+### Production Guidelines
+- Parameter validation before script creation
+- Comprehensive error handling and fallbacks
+- Security audit documentation for covenant logic
+- Testing requirements for mainnet deployment
+
+## 📈 Performance Optimization
+
+### Script Optimization Techniques
+- **Alt stack usage**: Store constants for reuse
+- **Endianness optimization**: Minimize reversal operations
+- **Preimage caching**: Avoid recomputation
+- **k=a=1 optimization**: Simplifies PUSHTX signature generation
+
+### Transaction Size Optimization
+- Optimized PUSHTX scripts: ~1KB for PELS implementation
+- CDN bundles: Multiple sizes for different use cases
+- Fee optimization: 91% reduction with 0.01 sats/byte
+
+## 🤝 Contributing to Documentation
+
+To improve this documentation:
+
+1. Follow the existing structure and formatting
+2. Include working code examples with explanations
+3. Add cross-references to related sections
+4. Provide both simple and advanced examples
+5. Include security considerations for all patterns
+
+## 🔗 External Resources
+
+### Official References
+- **[Bitcoin SV Documentation](https://bitcoinsv.com/)**
+- **[BIP143 Specification](https://github.com/bitcoin/bips/blob/master/bip-0143.mediawiki)**
+- **[nChain Research Papers](https://nchain.com/research/)**
+
+### Community Resources
+- **[SmartLedger-BSV GitHub](https://github.com/codenlighten/smartledger-bsv)**
+- **[NPM Package](https://www.npmjs.com/package/@smartledger/bsv)**
+- **[Examples Repository](../examples/)**
+
+---
+
+*Documentation for SmartLedger-BSV v3.1.1+ - Built for enterprise Bitcoin SV development*

package/docs/block.md

@@ -0,0 +1,46 @@
+# Bitcoin Block
+A Block instance represents the information of a block in the bitcoin network. Given a hexadecimal string representation of the serialization of a block with its transactions, you can instantiate a Block instance. Methods are provided to calculate and check the merkle root hash (if enough data is provided), but transactions won't necessarily be valid spends, and this class won't validate them. A binary representation as a `Buffer` instance is also valid input for a Block's constructor.
+
+```javascript
+// instantiate a new block instance
+var block = new Block(hexaEncodedBlock);
+
+// will verify that the corresponding block transactions match the header
+assert(block.validMerkleRoot());
+
+// blocks have several properties
+assert(block.header); // an instance of block header, more info below
+assert(block.transactions); // an array of transactions, more info below
+```
+
+For detailed technical information about a block please visit [Blocks](https://en.bitcoin.it/wiki/Blocks#Block_structure) on the Bitcoin Wiki.
+
+## Block Header
+Each instance of Block has a BlockHeader _(which can be instantiated separately)_. The header has validation methods, to verify that the block.
+
+```javascript
+// will verify that the nonce demonstrates enough proof of work
+assert(block.header.validProofOfWork());
+
+// will verify that timestamp is not too far in the future
+assert(block.header.validTimestamp());
+
+// each header has the following properties
+assert(block.header.version);
+assert(block.header.prevHash);
+assert(block.header.merkleRoot);
+assert(block.header.time);
+assert(block.header.bits);
+assert(block.header.nonce);
+```
+
+For more information about the specific properties of a block header please visit the [Block hashing algorithm](https://en.bitcoin.it/wiki/Block_hashing_algorithm) page on the Bitcoin Wiki.
+
+## Transactions
+The set of transactions in a block is an array of instances of [Transaction](transaction.md) and can be explored by iterating on the block's `transactions` member.
+
+```javascript
+for (var i in block.transactions) {
+  var transaction = block.transactions[i];
+}
+```

package/docs/ecies.md

@@ -0,0 +1,102 @@
+# ECIES
+`bsv/ecies` is a library that work with bsv's private/public keys. 
+
+It provide electrum compatible ECIES message by default.
+
+## Options
+The constructor accept several options
+
+- `ephemeralKey`: should use ephemeral private key to encrypt message. `true` by default. It's set to `false` automatically if you provide private key later.
+- `noKey`: should exclude encrypt public key in message. `false` by default, disabled if `ephemeralKey` is `true`. Typically, public key is included in message, so receiver need only his private key to decrypt. Receiver must use same option with sender, in order to decrypt message properly. 
+- `shortTag`: should use shorten HMAC in message. `false` by default. Receiver must use same option with sender, in order to decrypt message properly.
+
+## Examples
+
+### Message to Bob
+
+```javascript
+var bsv = require('bsv')
+var IES = require('bsv/ecies')
+
+var bob = bsv.PrivateKey()
+var bobPubkey = bob.publicKey
+
+// Send a message to bob
+var enc = new IES().publicKey(bobPubkey).encrypt('a message')
+// Bob decrypt a message
+var dec = new IES().privateKey(bob).decrypt(enc)
+```
+
+### Messages between Alice and Bob
+
+~~~javascript
+var bsv = require('bsv')
+var IES = require('bsv/ecies')
+
+var alice = bsv.PrivateKey()
+var alicePubkey = alice.publicKey
+var bob = bsv.PrivateKey()
+var bobPubkey = bob.publicKey
+
+var iesAlice = new IES({'nokey':true}).privateKey(alice).publicKey(bobPubkey)
+
+var iesBob = new IES({'nokey':true}).privateKey(bob).publicKey(alicePubkey)
+
+messageAlice = iesAlice.encrypt('Hello Bob')
+messageAliceDec = iesBob.decrypt(messageAlice)
+
+messageBob = iesBob.encrypt('Hi Alice')
+messageBobDec = iesAlice.decrypt(messageBob)
+~~~
+
+### Recover messages
+
+Sender can recover messages if `ephemeralKey` is `false`.
+
+~~~javascript
+var bsv = require('bsv')
+var IES = require('bsv/ecies')
+
+var alice = bsv.PrivateKey()
+var alicePubkey = alice.publicKey
+var bob = bsv.PrivateKey()
+var bobPubkey = bob.publicKey
+
+var iesAlice = new IES({'nokey':true}).privateKey(alice).publicKey(bobPubkey)
+
+var iesBob = new IES({'nokey':true}).privateKey(bob).publicKey(alicePubkey)
+
+messageAlice = iesAlice.encrypt('Hello Bob')
+messageAliceRecover = iesAlice.decrypt(messageAlice)
+~~~
+
+### ECDH Key
+
+Sometimes you may want to extract ECDH key for other use.
+
+~~~javascript
+var bsv = require('bsv')
+var IES = require('bsv/ecies')
+
+var alice = bsv.PrivateKey()
+var alicePubkey = alice.publicKey
+var bob = bsv.PrivateKey()
+var bobPubkey = bob.publicKey
+
+var iesAlice = new IES().privateKey(alice).publicKey(bobPubkey)
+
+var iesBob = new IES().privateKey(bob).publicKey(alicePubkey)
+
+var sharedSecret = iesAlice.ivkEkM
+var sharedSecret = iesBob.ivkEkM
+~~~
+
+### Bitcore ECIES
+
+Sometimes you may want to use bitcore sytle ECIES.
+
+~~~javascript
+var bsv = require('bsv')
+var IES = require('bsv/ecies').bitcoreECIES
+~~~
+