152 online 3 members  + Join RP Base  +
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
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:

  • 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)
Key FeaturesCore Wallet Functionality
  • 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
Advanced Features
  • 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
Storage & Deployment
  • 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
Network Integration
  • 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
System Architecture
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) │
│ └────────┬────────┘ │
│ ┌─────────────┴─────────────┐ │
│ ▼ ▼ │
│ ┌

…