xo-stack/packages/docs/src/architecture.md

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 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.

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.

The XO Stack's layered design provides several key advantages:

• 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.

graph TD
    Primitives("@xocash/primitives") --> Templates("@xocash/templates")
    Templates --> Stack("@xocash/stack")
    Stack --> Vue("@xocash/vue")
    Stack --> React("@xocash/react")

• @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 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 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 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.

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).