Architecture Document Amendments
This commit is contained in:
Jim Hamill
@@ -215,3 +215,10 @@ details summary {
|
||||
color: #f46666;
|
||||
overflow-wrap: break-word;
|
||||
}
|
||||
|
||||
/* MermaidJS */
|
||||
|
||||
.mermaid {
|
||||
display: flex;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
+175
-134
@@ -1,144 +1,185 @@
|
||||
# XO Stack Architecture Documentation
|
||||
# XO Stack Architecture
|
||||
|
||||
**NOTE: The XO Stack is still under heavy development. The following represents the broader architecture as at 2025-07-01 and several parts will still change.**
|
||||
|
||||
## 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.
|
||||
The XO Stack is a modular JavaScript/Node.js framework purpose-built for developing applications on the Bitcoin Cash (BCH) network. It tackles a common pain point in blockchain development: the tradeoff between monolithic, full-featured libraries and minimalist, low-level utilities.
|
||||
|
||||
## Core Design Philosophy
|
||||
Instead of forcing developers to choose one extreme, the XO Stack introduces a layered architecture. Each layer adds a higher level of abstraction, building on the functionality of the layer below it. This design empowers developers to adopt only the layers they need—whether it's just the core primitives for a command-line tool or the full stack for a feature-rich frontend/backend app.
|
||||
|
||||
### Object-Oriented Architecture
|
||||
The XO Stack's layered design provides several key advantages:
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
- **Selective Integration**: Developers can choose to implement only the layers relevant to their project, reducing bundle size and complexity
|
||||
- **Clear Separation of Concerns**: Each layer has a well-defined purpose, improving maintainability and testability.
|
||||
- **Scalable Abstraction**: Start simple, and layer in complexity as your needs grow—from wallet utilities to full app frameworks.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
EventEmitter --> BaseStore
|
||||
BaseStore --> StoreInMemory
|
||||
BaseStore --> StoreIndexedDB
|
||||
BaseStore --> StoreSQLite
|
||||
BaseStore --> StoreHTTP
|
||||
|
||||
EventEmitter --> BaseWallet
|
||||
BaseWallet --> WalletP2PKH
|
||||
BaseWallet --> WalletHD
|
||||
BaseWallet --> WalletMultisig
|
||||
|
||||
EventEmitter --> BaseBlockchain
|
||||
BaseBlockchain --> BlockchainInMemory
|
||||
BaseBlockchain --> BlockchainElectrum
|
||||
BaseBlockchain --> BlockchainChaingraph
|
||||
BaseBlockchain --> BlockchainP2PNetwork
|
||||
|
||||
EventEmitter --> BaseP2PChannel
|
||||
BaseP2PChannel --> P2PChannelLibP2P
|
||||
|
||||
EventEmitter --> BaseRates
|
||||
BaseRates --> RatesComposite
|
||||
BaseRates --> RatesCoinbase
|
||||
BaseRates --> RatesOracle
|
||||
|
||||
EventEmitter --> BaseBCMR
|
||||
BaseBCMR --> BCMRHTTP
|
||||
BaseBCMR --> BCMRComposite
|
||||
graph TD
|
||||
Primitives("@xocash/primitives") --> Templates("@xocash/templates")
|
||||
Templates --> Stack("@xocash/stack")
|
||||
Stack --> Vue("@xocash/vue")
|
||||
Stack --> React("@xocash/react")
|
||||
```
|
||||
|
||||
<!-- Clicking support if we ever want it
|
||||
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"
|
||||
-->
|
||||
- **@xocash/primitives** - The foundation layer containing core Bitcoin Cash utilities, cryptographic functions, and basic data structures
|
||||
|
||||
- **@xocash/templates** - The templating layer that allows developers to create and use sophisticated contract systems in both Dapps and Wallets.
|
||||
|
||||
- **@xocash/stack** - The main framework layer that combines primitives and templating capabilities into a cohesive development toolkit that includes blockchain connectivity, peer-to-peer networking, data storage, rate conversion, and specific wallet-type implementations (WalletP2PKH, WalletHD, etc).
|
||||
|
||||
- **@xocash/vue** and **@xocash/react** - Framework-specific integration layers that provide Vue.js and React components and utilities for frontend development
|
||||
|
||||
## Primitives (@xocash/primitives)
|
||||
|
||||
The `@xocash/primitives` package forms the foundation of the XO Stack, serving as a lightweight layer that provides convenient wrappers and validation methods for working with Bitcoin Cash primitives and utilities. This layer is network-naive and maintains minimal dependencies, relying only on the trusted `@bitauth/libauth` package to ensure security and reliability.
|
||||
|
||||
**Core Functions:**
|
||||
|
||||
- **Convenience Layer**: Simplifies common BCH operations with intuitive wrapper methods
|
||||
- **Validation Layer**: Ensures data integrity and type safety throughout the stack
|
||||
- **Standardization**: Provides consistent interfaces for BCH primitives across all higher layers
|
||||
|
||||
### Available Primitives and Utilities
|
||||
|
||||
- **Address** - Handles different BCH address formats (legacy, CashAddr) with conversion and validation capabilities
|
||||
|
||||
- **BlockHeader** - Manages Bitcoin Cash block header data structures and validation
|
||||
|
||||
- **Bytes** - Provides utilities for byte array manipulation and conversion operations
|
||||
|
||||
- **Encrypter** - Handles encryption and decryption operations for secure data handling
|
||||
|
||||
- **ExtJson** - Extended JSON utilities for serializing/deserializing Javascript payloads (Uint8Array, BigInt).
|
||||
|
||||
- **Hasher** - Cryptographic hashing functions including SHA-256 and other BCH-specific hash operations
|
||||
|
||||
- **HDPrivateNode** - Hierarchical Deterministic private key derivation and management
|
||||
|
||||
- **HDPublicNode** - Hierarchical Deterministic public key derivation for wallet applications
|
||||
|
||||
- **Mnemonic** - BIP39 mnemonic phrase generation, validation, and seed conversion utilities
|
||||
|
||||
- **PrivateKey** - Private key generation, validation, and cryptographic operations
|
||||
|
||||
- **PublicKey** - Public key derivation, validation, and verification utilities
|
||||
|
||||
- **Satoshis** - Precise Bitcoin Cash amount handling with decimal conversion and validation
|
||||
|
||||
- **Script** - Bitcoin Cash script parsing, compilation, and execution utilities
|
||||
|
||||
- **Transaction** - Complete transaction building, signing, and validation functionality
|
||||
|
||||
## Templates (@xocash/templates)
|
||||
|
||||
This is being fleshed out currently. The ideal is to segregate Templates from Transports (e.g. make CashConnect a specific implementation that handles the Transport). Consider its position in the Stack very tentative as we may not be able to maintain SoC as has been described here.
|
||||
|
||||
## Stack (@xocash/stack)
|
||||
|
||||
The `@xocash/stack` package represents the main framework layer that combines primitives with advanced templating and connectivity capabilities. This comprehensive toolkit provides several important pieces for production Bitcoin Cash applications, including blockchain connectivity, peer-to-peer networking, data storage, rate conversion, and wallet implementations.
|
||||
|
||||
**Architecture Design:**
|
||||
|
||||
- **Bridge Pattern Implementation**: Common interfaces are defined for core services (Blockchain, P2P, Storage, Rates, Wallets) with specific implementations for different environments and use-cases (e.g. Web and Backend). See [here](https://refactoring.guru/design-patterns/bridge) for more information on Bridge Patterns.
|
||||
- **Dependency Injection Architecture**: Providers accept other providers as dependencies through constructor injection, enabling flexible composition and easy testing through mock implementations. See [here](https://en.wikipedia.org/wiki/Dependency_injection) for more information on Dependency Injection.
|
||||
- **Observer Pattern Integration**: All providers extend a custom EventEmitter utility, enabling integration with frontend frameworks through reactive event handling or Vanilla-JS. See [here](https://refactoring.guru/design-patterns/observer) for more information on Observer Patterns.
|
||||
|
||||
**Core Functions:**
|
||||
|
||||
- **Blockchain Connectivity**: Multiple provider options for connecting to the Bitcoin Cash network
|
||||
- **Peer-to-Peer Networking**: Direct P2P communication capabilities for decentralized applications
|
||||
- **Data Persistence**: Flexible storage solutions from in-memory to blockchain-based storage
|
||||
- **Rate Conversion**: Real-time cryptocurrency exchange rate data from multiple sources
|
||||
- **Wallet Management**: Ready-to-use wallet implementations for various use cases
|
||||
- **Event-Driven Architecture**: Reactive programming support for frontend framework integration
|
||||
|
||||
### Available Interfaces and Providers
|
||||
|
||||
**Blockchain Providers** - Network connectivity and blockchain data access
|
||||
|
||||
- **BlockchainChaingrph** - Integration with Chaingraph indexing service for advanced queries
|
||||
- **BlockchainElectrum** - Electrum server connectivity for lightweight blockchain access
|
||||
- **BlockchainInMemory** - In-memory blockchain simulation for testing and development
|
||||
|
||||
**P2P Providers** - Direct peer-to-peer network communication
|
||||
|
||||
- **P2PLibP2p** - LibP2P-based networking for decentralized application communication
|
||||
|
||||
**Rate Providers** - Cryptocurrency price and conversion data
|
||||
|
||||
- **RatesBitPay** - BitPay exchange rate API integration
|
||||
- **RatesCoinbase** - Coinbase API for market data
|
||||
- **RatesCryptoCompare** - CryptoCompare API for comprehensive price feeds
|
||||
- **RatesOracles** - Decentralized oracle network price data
|
||||
- **RatesComposite** - Combines multiple rate providers for increased reliability and accuracy
|
||||
|
||||
**Storage Providers** - Data persistence and retrieval solutions
|
||||
|
||||
- **StoreBlockchain** - On-chain data storage using Bitcoin Cash transactions
|
||||
- **StoreIndexedDB** - Browser-based IndexedDB for offline-capable web applications
|
||||
- **StoreInMemory** - Volatile memory storage for temporary data and testing
|
||||
- **StoreLocalStorage** - Browser localStorage for simple client-side persistence
|
||||
- **StoreHTTP** - Remote HTTP server storage for centralized data management
|
||||
|
||||
**Activities** - High-level data orchestration layer that provides eventually-consistent synchronization across multiple storage providers and data sources
|
||||
|
||||
**Wallet Providers** - Bitcoin Cash wallet implementations
|
||||
|
||||
- **WalletHD** - Hierarchical Deterministic wallet with multi-address support
|
||||
- **WalletP2PKH** - Simple Pay-to-Public-Key-Hash wallet for basic transactions
|
||||
- **WalletMultisig** - Multisignature Wallet implementation
|
||||
|
||||
### Available Utilities
|
||||
|
||||
- **EventEmitter** - Custom event system for reactive programming and framework integration. All provider interfaces inherit from this.
|
||||
|
||||
- **ExponentialBackoff** - Retry mechanism with exponential delay for handling network failures gracefully
|
||||
|
||||
- **InverseBloomFilter** - Probabilistic data structure for efficient set membership testing and synchronization
|
||||
|
||||
- **Memoizer** - Caching utility for expensive computations and API calls
|
||||
|
||||
- **SSESession** - Server-Sent Events client for real-time data streaming
|
||||
|
||||
- **SSESession (MsgPackr)** - High-performance SSE implementation with MessagePack serialization for reduced bandwidth
|
||||
|
||||
- **UUID** - Universally Unique Identifier generation for distributed systems
|
||||
|
||||
## Vue (@xocash/vue)
|
||||
|
||||
The `@xocash/vue` package provides seamless Vue.js integration for the XO Stack, automatically binding provider state to Vue's reactive system. This layer eliminates the need for manual state management by creating reactive wrappers around core providers, enabling real-time UI updates whenever blockchain data, wallet balances, or network status changes.
|
||||
|
||||
**Key Features:**
|
||||
|
||||
- **Automatic Reactivity**: Provider state changes automatically trigger Vue component re-renders
|
||||
- **Zero Boilerplate**: No manual event listeners or state synchronization required
|
||||
- **Type Safety**: Full TypeScript support with proper type inference for Vue templates
|
||||
- **Composition API Ready**: Designed to work seamlessly with Vue 3's Composition API
|
||||
|
||||
### Available Reactive Classes
|
||||
|
||||
- **ReactiveActivities** - Real-time data synchronization monitoring with automatic UI updates for eventually-consistent operations across multiple storage sources
|
||||
|
||||
- **ReactiveBlockchain** - Live blockchain state including block height, network status, and connection health
|
||||
|
||||
- **ReactiveStorage** - Reactive data persistence with automatic synchronization between local storage and UI components
|
||||
|
||||
- **ReactiveRates** - Live cryptocurrency exchange rates with automatic price updates and conversion calculations
|
||||
|
||||
- **ReactiveWallet** - Real-time wallet state including balances, transaction history, and address management with instant UI updates
|
||||
|
||||
## React (@xocash/react)
|
||||
|
||||
This has not yet been written. The ideal is to use a similar structure to the Vue implementation above. However, React does not use proxies for reactivity (as Vue does), so we will likely have to do this using a React Store framework.
|
||||
|
||||
Early PoC's I wrote indicate that we **may** be able to avoid a specific Store implementation (thus, keeping it more "purely React"), but I recall there being some constraints around nested-reactivity.
|
||||
|
||||
## Contributing to Stack
|
||||
|
||||
Refer to [CONTRIBUTING.md](https://gitlab.com/GeneralProtocols/xo/stack/-/blob/development/CONTRIBUTING.md?ref_type=heads).
|
||||
|
||||
## Potential Changes to High-Level Architecture
|
||||
|
||||
- Some Provider Implementations might be split into their own packages if they drag in heavy dependencies.
|
||||
- Where CashConnect will sit is being fleshed out at time of writing. Right now, I suspect it will likely be its own package as a Provider Implementation: CashConnect might ultimately refer to Wallet/Dapp Connectivity, where as Templates are treated somewhat akin to a Primitive.
|
||||
- Additional higher-level packages may be added (e.g. an `@xocash/extras` that might contain some use-case specific conveniences).
|
||||
|
||||
Reference in New Issue
Block a user