FreeScript
libspiffy
by twostack · version 2026.11.16 · updated yesterday
No reviews yet
- Downloads
- 0
- Reviews
- 0
- Size
- 4.4 MB
- Code check
- Clean
- Licence
- MIT
- Released
- Nov 2026
An actor-based Bitcoin SPV Wallet Library
LibSpiffy - Event-Sourced Bitcoin Wallet
An actor-based Bitcoin wallet implementation using event sourcing, CQRS, and SPV (Simplified Payment Verification) built with the Dactor/Eventador/DuraQ stack.
Architecture Overview
LibSpiffy implements a sophisticated Bitcoin wallet system using modern architectural patterns:
LibSpiffy implements a CQRS (Command Query Responsibility Segregation) architecture with complete separation between write operations (commands → events → EventStore) and read operations (queries → ReadModels).
┌───────────────────────────────────────────────────────────────────────────┐
│ LibSpiffy CQRS Architecture │
├───────────────────────────────────────────────────────────────────────────┤
│ │
│ PUBLIC API (import 'package:libspiffy/coordinator.dart') │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ WalletCoordinatorActor (Unified Facade) │ │
│ │ • Send: CreateWalletCommand, PayInvoiceCommand, GetBalanceQuery │ │
│ │ • Recv: WalletCreatedEvent, PaymentReadyEvent, BalanceResponse │ │
│ │ • Answers each request with its own reply (ask), channel P2P │ │
│ └────────────────────────────────┬───────────────────────────────────┘ │
│ │ Internal delegation │
│ COMMAND SIDE (Write Operations) │ │
│ ┌──────────────────┐ ┌──────┴─────────────┐ │
│ │ Wallet Manager │─────▶│ Invoice Coordinator│ │
│ │ Actor │ │ Actor │ │
│ │ • Routes cmds │ │ • Routes invoice │ │
│ │ • Spawns aggr. │ │ commands │ │
│ │ • Multi-wallet │ │ • Spawns invoice │ │
│ └────────┬─────────┘ │ aggregates │ │
│ │ └──────────┬─────────┘ │
│ ▼ ▼ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ Wallet │ │ Invoice │ │
│ │ Aggregate │ │ Aggregate │ │
│ │ • Validates │ │ • Validates │ │
│ │ • Emits events │ │ • Emits events │ │
│ └────────┬───────┘ └────────┬───────┘ │
│ └────────────┬────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Event Store │ (Write-Only from Aggregates) │
│ │ (Eventador) │ │
│ └────────┬────────┘ │
│ ═════════════════════╪═══════════════════════════════════════════════ │
│ ▼ Event Stream │
│ ┌─────────────────┐ │
│ │Projection Actors│ (Read-Only from EventStore) │
│ └────────┬────────┘ │
│ ┌─────────────┴─────────────┐ │
│ ▼ ▼ │
│ ┌
…
An actor-based Bitcoin wallet implementation using event sourcing, CQRS, and SPV (Simplified Payment Verification) built with the Dactor/Eventador/DuraQ stack.
Architecture Overview
LibSpiffy implements a sophisticated Bitcoin wallet system using modern architectural patterns:
- Event Sourcing: All wallet state changes are captured as immutable events
- CQRS: Clear separation between commands (write operations) and queries (read operations)
- Actor Model: Concurrent, fault-tolerant processing using Dactor
- SPV: Lightweight Bitcoin verification using merkle proofs
- Hybrid Stack: Combines Dactor (actors), Eventador (event store), and DuraQ (workflows)
- HD wallet address generation and management
- Wallet import (xpub watch-only, WIF private key)
- UTXO tracking with confirmation status
- Transaction creation and signing
- SPV transaction verification with merkle proofs (BEEF/BUMP)
- Multi-wallet support with isolation
- Event-sourced state with full audit trail
- Invoice-based payment system for simplified SPV validation
- Multi-output invoices (P2PKH, P2MS multisig, OP_RETURN metadata, Plugin-delegated outputs)
- Plugin system for custom script types and token protocols (ScriptPlugin, TransactionBuilderPlugin)
- Payment channels for off-chain micropayments with on-chain settlement
- Benford distribution UTXO splitting for transaction privacy
- UTXO holds and reservations with automatic cleanup
- Snapshot support for performance optimization
- Real-time balance calculations
- ARC (Authoritative Response Component) service integration for broadcasting and the policy fee rate every transaction pays
- Transaction fee calculation from BEEF data
- Isar embedded database for mobile/desktop
- PostgreSQL backend for server-side deployments
- In-memory storage for development and testing
- AES-256-GCM encrypted key storage (xpub/xpriv)
- Pluggable storage interfaces for custom backends
- Bitcoin P2P network connectivity via SpiffyNode
- Block header synchronization (P2P network and CDN-based fast sync)
- BEEF (Background Evaluation Extended Format) transaction validation
- BUMP (BSV Universal Merkle Path) merkle proof validation
- Merkle proof validation against header chain
- ARC (Authoritative Response Component) service integration
- WhatsOnChain blockchain data source for wallet import
LibSpiffy implements a CQRS (Command Query Responsibility Segregation) architecture with complete separation between write operations (commands → events → EventStore) and read operations (queries → ReadModels).
`┌───────────────────────────────────────────────────────────────────────────┐
│ LibSpiffy CQRS Architecture │
├───────────────────────────────────────────────────────────────────────────┤
│ │
│ PUBLIC API (import 'package:libspiffy/coordinator.dart') │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ WalletCoordinatorActor (Unified Facade) │ │
│ │ • Send: CreateWalletCommand, PayInvoiceCommand, GetBalanceQuery │ │
│ │ • Recv: WalletCreatedEvent, PaymentReadyEvent, BalanceResponse │ │
│ │ • Answers each request with its own reply (ask), channel P2P │ │
│ └────────────────────────────────┬───────────────────────────────────┘ │
│ │ Internal delegation │
│ COMMAND SIDE (Write Operations) │ │
│ ┌──────────────────┐ ┌──────┴─────────────┐ │
│ │ Wallet Manager │─────▶│ Invoice Coordinator│ │
│ │ Actor │ │ Actor │ │
│ │ • Routes cmds │ │ • Routes invoice │ │
│ │ • Spawns aggr. │ │ commands │ │
│ │ • Multi-wallet │ │ • Spawns invoice │ │
│ └────────┬─────────┘ │ aggregates │ │
│ │ └──────────┬─────────┘ │
│ ▼ ▼ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ Wallet │ │ Invoice │ │
│ │ Aggregate │ │ Aggregate │ │
│ │ • Validates │ │ • Validates │ │
│ │ • Emits events │ │ • Emits events │ │
│ └────────┬───────┘ └────────┬───────┘ │
│ └────────────┬────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Event Store │ (Write-Only from Aggregates) │
│ │ (Eventador) │ │
│ └────────┬────────┘ │
│ ═════════════════════╪═══════════════════════════════════════════════ │
│ ▼ Event Stream │
│ ┌─────────────────┐ │
│ │Projection Actors│ (Read-Only from EventStore) │
│ └────────┬────────┘ │
│ ┌─────────────┴─────────────┐ │
│ ▼ ▼ │
│ ┌
…