Use Hash256

.madgerc

@@ -0,0 +1,7 @@
+{
+  "excludeRegExp": [
+    "^.+?/dist/.+$",
+    "\\.test\\.js$",
+    "\\.spec\\.js$"
+  ]
+}

packages/docs/package.json

@@ -20,6 +20,7 @@
     "typedoc": "^0.27.5",
     "typedoc-plugin-markdown": "^4.3.2",
     "typedoc-vitepress-theme": "^1.1.1",
-    "vitepress": "^1.3.4"
+    "vitepress": "^1.3.4",
+    "vitepress-plugin-mermaid": "^2.0.17"
   }
 }

packages/docs/src/.vitepress/config.ts

@@ -1,4 +1,5 @@
 import { defineConfig } from 'vitepress';
+import { withMermaid } from 'vitepress-plugin-mermaid';
 import typedocSidebar from '../api/typedoc-sidebar.json';
 
 // Special cases map for acronyms and exceptions
@@ -62,7 +63,7 @@ function convertNavToPascalCase(nav: Array<any>) {
 }
 
 // https://vitepress.dev/reference/site-config
-export default defineConfig({
+export default withMermaid({
   outDir: '../dist',
   title: 'Stack',
   description:
@@ -97,6 +98,7 @@ export default defineConfig({
           text: 'Guide',
           items: [
             { text: 'Quick Start', link: '/quick-start' },
+            { text: 'Architecture', link: '/architecture' },
             { text: 'Best Practices', link: '/api-examples' },
           ],
         },

packages/docs/src/architecture.md

@@ -0,0 +1,122 @@
+# XO Stack Architecture Documentation
+
+## Overview
+
+The XO Stack is a comprehensive framework designed for building applications on the Bitcoin Cash (BCH) network. It employs an Object-Oriented architecture that prioritizes modularity, extensibility, and developer experience.
+
+## Core Design Philosophy
+
+### Object-Oriented Architecture
+
+The XO Stack adopts an Object-Oriented design for several key reasons:
+
+1. **Encapsulation and Data Privacy**
+   - Internal implementation details are hidden from consumers
+   - State management is contained within specific classes
+   - Clear boundaries between different system components
+   - Reduced likelihood of state-related bugs
+
+2. **Adapter Pattern Benefits**
+   - Pluggable components that can be swapped without changing application code
+   - Easy to add new implementations for different environments
+   - Testing simplified through mock adapters
+   - Reduced vendor lock-in
+
+3. **Developer Experience**
+   - Strong IDE support with autocomplete suggestions
+   - Type safety when using TypeScript
+   - Clear inheritance hierarchies
+   - Intuitive method discovery through class interfaces
+   - Familiar paradigm for most developers
+
+4. **Code Organization**
+   - Logical grouping of related functionality
+   - Clear separation of concerns
+   - Consistent patterns across the codebase
+   - Easier to maintain and extend
+
+## Core Components
+
+### EventEmitter
+
+The EventEmitter serves as the foundational building block of the XO Stack. It provides:
+
+- Pub/sub functionality for component communication
+- Framework-agnostic event handling
+- Seamless integration with frontend frameworks
+- Consistent event patterns across the stack
+
+### Base Classes
+
+#### BaseStore
+
+The storage adapter interface that defines how data is persisted:
+
+- Abstract methods for CRUD operations
+- Consistent API across storage implementations
+- Transaction support
+- Query capabilities
+
+Available implementations:
+- **StoreInMemory**: Volatile storage for testing and development
+- **StoreIndexedDB**: Browser-based persistent storage
+- **StoreSQLite**: Native application storage solution
+
+#### BaseBlockchain
+
+Defines the interface for interacting with the BCH network:
+
+- Network communication abstraction
+- Transaction broadcasting
+- Block and transaction monitoring
+- Network status management
+
+Available implementations:
+- **BlockchainInMemory**: Mock blockchain for testing
+- **BlockchainElectrum**: Production-ready Electrum protocol client
+
+#### BaseWallet
+
+Represents different wallet types for managing BCH:
+
+- Key management
+- Address generation
+- Transaction signing
+- Balance tracking
+
+Available implementations:
+- **WalletP2PKH**: Basic Pay-to-Public-Key-Hash wallet
+- **WalletHD**: Hierarchical Deterministic wallet implementation
+  - **WalletXO**: Extended HD wallet with XO-specific features
+
+## Architecture Diagram
+
+```mermaid
+graph LR
+    EventEmitter --> BaseStore
+    BaseStore --> StoreInMemory
+    BaseStore --> StoreIndexedDB
+    BaseStore --> StoreSQLite
+
+    EventEmitter --> BaseWallet
+    BaseWallet --> WalletP2PKH
+    BaseWallet --> WalletHD
+    WalletHD --> WalletXO
+
+    EventEmitter --> BaseBlockchain
+    BaseBlockchain --> BlockchainInMemory
+    BaseBlockchain --> BlockchainElectrum
+
+    click EventEmitter "https://example.com/docs/EventEmitter" "Go to EventEmitter documentation"
+    click BaseStore "https://example.com/docs/BaseStore" "View BaseStore documentation"
+    click StoreInMemory "https://example.com/docs/StoreInMemory" "View StoreInMemory documentation"
+    click StoreIndexedDB "https://example.com/docs/StoreIndexedDB" "View StoreIndexedDB documentation"
+    click StoreSQLite "https://example.com/docs/StoreSQLite" "View StoreSQLite documentation"
+    click BaseWallet "https://example.com/docs/BaseWallet" "View BaseWallet documentation"
+    click WalletP2PKH "https://example.com/docs/WalletP2PKH" "View WalletP2PKH documentation"
+    click WalletHD "https://example.com/docs/WalletHD" "View WalletHD documentation"
+    click WalletXO "https://example.com/docs/WalletXO" "View WalletXO documentation"
+    click BaseBlockchain "https://example.com/docs/BaseBlockchain" "View BaseBlockchain documentation"
+    click BlockchainInMemory "https://example.com/docs/BlockchainInMemory" "View BlockchainInMemory documentation"
+    click BlockchainElectrum "https://example.com/docs/BlockchainElectrum" "View BlockchainElectrum documentation"
+```

packages/docs/src/xo-libauth-comparison.md

@@ -174,13 +174,13 @@ To minimize the amount of data necessary for recovery and maintain backwards com
 The below is very rough (I'm not suggesting this as a practical implementation, but just to illustrate the approach vaguely).
 
 | Key                    | Derivation (Rough Example)                                       | Comments                              |
-|------------------------|---------------------------------------------------------------|---------------------------------------|
+|------------------------|------------------------------------------------------------------|---------------------------------------|
 | Default HD Wallet      | Root Seed -> m/44'/145'/0'                                       | Backwards compat with current Wallets |
-| WalletId               | sha256(sha256(rootSeed) + sha256('walletId'))                 | Identifier for Wallet                 |
-| EncryptionKey          | sha256(sha256(rootSeed) + sha256('encryptionKey'))            | Encrpytion Key for Activities         |
-| SigningKey             | sha256(sha256(rootSeed) + sha256('signingKey'))               | Signing key for Identity/Activity     |
-| Intra-Wallet Templates | sha256(sha256(rootSeed) + sha256('template:${templateHash}')) | Derive seed per template              |
-| Web-based Dapps        | sha256(sha256(rootSeed) + sha256(`domain:${domain}'))         | Derive seed per domain                |
+| WalletId               | hash256(hash256(rootSeed) + hash256('walletId'))                 | Identifier for Wallet                 |
+| EncryptionKey          | hash256(hash256(rootSeed) + hash256('encryptionKey'))            | Encrpytion Key for Activities         |
+| SigningKey             | hash256(hash256(rootSeed) + hash256('signingKey'))               | Signing key for Identity/Activity     |
+| Intra-Wallet Templates | hash256(hash256(rootSeed) + hash256('template:${templateHash}')) | Derive seed per template              |
+| Web-based Dapps        | hash256(hash256(rootSeed) + hash256(`domain:${domain}'))         | Derive seed per domain                |
 
 NOTE: WalletID, EncryptionKey and SigningKey could **probably** use a BIP32 Derivation Path instead of hashing a new seed from the root seed (and this might be more ideal/sensible?).